Work in Domino happens in projects. Projects contain data, code, and environment settings, and the entire project is tracked and revisioned automatically. A new commit is written to a project each time its files are changed by user action, or by the execution of code in the project. Users in Domino can create their own new projects, invite other users to collaborate on them, and export data or results for consumption by other projects.
Domino manages a collection of files for every project. Files can be added to a project in the following ways:
- uploaded from the Domino web application
- uploaded from the Domino Command Line Interface
- uploaded via the Domino API
- created and edited in the Domino web application
- generated by the execution of code in a workspace or run
Each of these ways of modifying a project’s files creates a new revision of the project. Whenever you start a Run from a Domino project, the files in that project are loaded onto the machine hosting the Run. This machine is known as the executor. The project files are mounted in the /mnt directory, which is in the filesystem root of the executor. Domino keeps track of changes to this directory. When a Run completes, Domino will record changes to /mnt as a new revision of the project. To learn more about how files are loaded into and changed by Runs, read about the Domino service filesystem.
It is also possible to add external Git repositories to projects. Doing so makes the contents of those repositories available in runs and workspaces in the /repos directory of the executor. To learn more, read about Git repositories in Domino.
There are several special files reserved by Domino. These files control the revisioning behavior, results display, and run comparison features of a project.
All Domino projects are initialized with a README file, which is accessible through the Overview section of your project. README files are typically used to give readers a general overview of a project. The contents of the README file in your project are written in Markdown, a lightweight and easy-to-read/write markup language.
If you plan to reference other project files within the README file, make sure you prepend raw/latest to the beginning of a file's relative path.
For example, consider a file named overview.jpg stored in a folder called images/ in your Domino files, such that the file's path is images/overview.jpg. To reference this file within the README file, the complete path would be raw/latest/images/overview.jpg.
By default, all projects include a .dominoignore file in the project root folder. This file functions similarly to a .gitignore file, and can be used to exclude certain file patterns from being written to future revisions of the project files. Domino will ignore files that match the specified patterns whenever a new revision is created. This includes revisions created by syncing from your local machine using the CLI, as well as new revisions created by a run or workspace session.
To ignore a file pattern, add it to .dominoignore. Patterns can be filenames, folder names, or UNIX shell regular expressions. Adding a folder will ignore it along with all of its contents. Note that the * symbol in UNIX shell regular expressions is a wildcard, and will match. All paths must be relative to the project root. Take a look at the contents of the default .dominoignore in one of your projects to see commented examples of excluded patterns.
A .git/ directory is always ignored by Domino sync operations, even if that pattern is not listed in .dominoignore.
Domino projects include a special file named .dominoresults. This file controls which files appear in the results dashboard for this project’s runs. It is constructed similarly to .dominoignore, but lists file patterns to include instead of exclude. If no patterns are listed in this file, all files changed by a run will be included in the results dashboard. If any patterns are listed in this file, only files which match those patterns will be included in the results dashboard for this project’s runs.
For example, a .dominoresults file that contains the following lines will only display the two specified files in the results dashboard.
A .dominoresults file that contains the following lines will display all PDF files in the project, plus any PNG files that are in the results/ folder.
Domino’s run comparison feature checks for a file named dominostats.json to compare key measurables from individual runs. This file is automatically deleted at the beginning of a run, and will only exist in the project revision produced by a run if a fresh version is written during execution. Read more about runs to learn the details of how this feature works.
There are several important settings attached to every Domino project. To access project settings, open a project overview and click Settings from the left sidebar.
Hardware tiers describe the compute hardware that will be used for project executors. Executors can either be virtual instances from a cloud services provider, or a machine running in your deployment’s on-premise data center. Local administrators will configure the hardware tiers available for your deployment. Use the Hardware & Environment tab of the project settings to set a specific hardware tier for your project.
You should choose a hardware tier that will provide the performance your workflow needs, bearing in mind the cost of the hardware in cloud deployments, and the impact of your tenancy on local hardware in on-premise deployments. Domino will use this hardware tier for all runs started in the project. When the hardware tier is changed, it will be the default for future runs in the project, although the default can be overridden when starting a run that requires alternate hardware.
Compute environments are specifications for containers in which Domino projects will run. Users can create new environments and access public environments shared in their deployment or organization. Whenever a new executor is launched or provisioned for use with a project, Domino loads the compute environment specified in the Hardware & Environment tab of the project settings.
Click to read more about how environments work.
Domino pulls environment variables from three sources whenever it loads a run or workspace:
- User, project, and hardware information. These are stored in variables set by Domino automatically.
- Environment variables defined in the user profile of the user starting a run.
- Environment variables defined in the Hardware & Environment tab of the project settings.
These environment variables can be used to securely store keys and credentials needed by the project. The names of these variables must start with a letter, and contain only alphanumeric characters and underscores.
In Domino 3.5+, projects can be labeled with configurable stages that track their progress through a data science life cycle. If your Domino administrator has configured project stages, you will see the current stage of your project displayed in brackets below the project name in the project menu. If you click the project name, a panel will open with a dropdown menu that you can use to change the project stage if you are an owner or contributor on the project.
Tracking your project through the stages used by your team will help your colleagues understand what kind of work is happening in the project and how they can contribute. Changing the stage of a project is an event that will appear in the project's activity feed.
Projects also have a status, which is indicated by the colored pip next to the project name.
A project's status can be:
GreenMarks an active and progressing project.
RedMarks an active project that is blocked.
GreyMarks a completed project.
By default, new projects are set to a green, active status. To modify a project's status, click the project name at the top of the project menu to open a panel with options to mark a project as blocked or complete. When you do so, you'll be given the option to supply a message describing the blocker or end result of the project. Changing the status of a project is an event that will appear in the project's activity feed with an attached comment thread, so project collaborators can discuss blockers or project conclusions.
Marking a project as blocked
Project owners and contributors can mark a project as blocked. You should mark a project as blocked when you need assistance from colleagues or administrators to make progress. Domino administrators and your project collaborators will receive an email notification when you mark a project as blocked. Some common cases where raising a blocker can help are:
- You need assistance setting up additional tools in a Domino environment
- You need access to new data sources
- You need hardware capabilities not covered by your current hardware tier
The same menu used to mark a project as blocked can be used to unblock the project, which returns it to a green, active status.
Marking a project as complete
Project owners and contributors can mark a project as complete. This allows for final conclusions and products to be recorded in the project's activity feed, and filters the project out of active project views. On your projects overview, you will find a checkbox to Show completed projects you can use to find projects that have been marked as complete.
The same menu used to mark a project as complete can be used to reopen the project, which returns it to a green, active status. Note that a project marked as complete is still a fully functional Domino project. You can modify its files and start Runs in it, but before doing so you may want to consider reopening the project to indicate that work is continuing.
Click Activity in the project menu to open the project's Activity Feed. On this page you will see the history of activity in the project, including:
- Jobs started
- Workspaces started
- Comments left on Jobs or Workspaces
- Comments left on files
- Project stage changes
- Blockers raised or resolved
- Files created, edited, or deleted in the Domino UI
- Files modified in Workspace sessions
- Models or Apps published
- Scheduled Jobs published or edited
You can use the dropdown menu at the top of the feed to filter out comments, Jobs, or Workspaces. If you check two successfully completed Runs in the feed, you can use the comparison button next to the filter menu to open a Run comparison.
It is possible to import content from one Domino project into another. The importing project may have access to the exporting project’s files, environment variables, or both, depending on configuration. During runs with imported files, each project directory is located at /mnt/<username>/<project name>. When a run or workspace is started, these files are pulled in alongside the current project’s files. Imported directories are read-only.
The path of your project will also change from /mnt to /mnt/<username>/<project name> when you have imported projects. If you have hardcoded any paths in your project code to /mnt, you should replace them with paths that use the $DOMINO_WORKING_DIR environment variable.
From the project overview page, in the left sidebar click Exports under Settings. From this interface you can enable exports for the project’s files and environment variables separately, or export the project files as a Python or R package. If none of these are enabled, other projects will not be able to import anything from this project.
By default, projects will make their latest revision available for export when configured. You can also make revisions produced by specific runs available for import by tagging those runs with release. From the runs page of a project, select the runs you want to export by clicking the checkbox next to them, then click the tag button at the top of the list. Enter the exact string release to mark the revision created by the selected runs as available for export.
From the Files page of the project you want to import into, click the Other Projects tab. Enter the path to the project you want to import, with the format <username>/<project-name>. The following conditions must be true for you to successfully import a project:
- You must have Project Importer, Contributor, or Owner permissions on the project.
- The project must be configured for export.
After adding a project that exports files, you can choose which revision of the project files you want to import with the Release menu.