A cnvrg project is the space in which you hold everything related to a specific machine learning problem or domain. You work and collaborate on projects.
The topics in this page:
- Creating a project
- Project Dashboard
- Git Integration
- Project Settings
- Slack Integration
- Project Secrets
# Creating a project
You can create a project in cnvrg using the web UI or the cnvrg CLI.
Using the web UI
Navigate to the Projects tab and click Start Project.
Type in a title for the project and click Create.
The project is added and the project dashboard is displayed.
Using the cnvrg CLI
With cnvrg CLI commands, you can create an empty project or create a project linked to an existing folder.
Create an empty cnvrg project
cnvrg new <project-name>
When you run the
cnvrg newCLI command, cnvrg creates a default project tree:
total 16 drwxr-xr-x 8 256B Jul 14 23:58 . drwxr-xr-x 8 256B Jul 14 23:58 .. drwxr-xr-x 4 128B Jul 14 23:58 .cnvrg -rw-r--r-- 1 139B Jul 14 23:58 .cnvrgignore -rw-r--r-- 1 404B Jul 14 23:58 README.md drwxr-xr-x 2 64B Jul 14 23:58 models drwxr-xr-x 2 64B Jul 14 23:58 notebooks drwxr-xr-x 5 160B Jul 14 23:58 src
The new project will now be created in cnvrg and you can make changes in your local directory.
To sync changes between the online project and your local repository use the
Create a cnvrg project and link it to an existing folder
You can create a cnvrg project and link it to a folder, with a single command.
- Navigate into the folder.
- From there, run the
cnvrg link [--title='project_name'] --sync
For more information on the
cnvrg linkcommand, see the cnvrg CLI documentation.
# Project Dashboard
The dashboard shows a summary of your project: the number of experiments run, active endpoints, active workspaces and active apps, as well as a feed of all activity in the project.
On the left, the dashboard presents tabs for easy access to project research, files and more.
From the dashboard, you can start or access a running workspace and link your project to a Git repo.
cnvrg offers out-of-the-box version control for your project. With the simple drag-and-drop interface or the cnvrg CLI, you can have your project files (code, artifacts) automatically tracked and versioned.
cnvrg will automatically create new commits for experiments and workspaces syncs and keep track of all your projects' files. When connected to git, only the designated
output folder will be synced and managed by cnvrg.
# Change commits
On the Files tab of a project, you can view a different commit by clicking the Version menu, and then choose a different commit. You can also change commits while viewing a specific file.
# File viewer
cnvrg has inline support for rendering a viewing the following file types:
- scipts (python, R, txt, .sh, yaml etc.)
- Static Jupyter notebooks
Simply navigate to the file inside the Files tab and click it to view it.
# Compare different versions of a file
As cnvrg is tracking multiple versions of your files, you can compare the difference between saved versions using the Diff button. This is great for comparing scripts and Jupyter notebooks.
To compare the difference between two versions of the same file:
- Navigate to the file you want to compare.
- In the Version drop down list, choose the version you want to compare against.
- Click Diff on the second version's page.
cnvrg will compare th chosen version and the current version and highlight all the changes.
# Diff for scripts and text files
When comparing scripts, cnvrg will place the scripts alongside each other and highlight the deletions and additions.
# Diff for static Jupyter notebooks
When comparing Jupyter Notebooks, cnvrg will align each cell alongside the corresponding previous version and highlight deletions and additions. Markdown and Code cells are designated as well.
When working on a workspace or from your local environment (PyCharm and others), all changes will be pushed to the
master branch in cnvrg version control.
Every experiment you run will create its own separate branch for the changes it makes. For example, if you run two experiments in parallel, with the same
start_commit, they will both create two different
end_commits. This way, you can make sure that everything is tracked and that no conflicts or unnecessary merges are made.
.cnvrgignore file to ignore files that you don't want to be synced to the platform.
To sync your project to cnvrg, run:
Find more information for using the CLI with your project here.
# Git Integration
cnvrg has native integration with Git. Leveraging this feature allows you to use an external Git repository to track your code and files while using cnvrg to track your data science resources (models, experiments and more).
When integrating cnvrg project with Git, cnvrg will automatically clone your Git project before starting your job and you can specify a branch and commit when starting a workspace, experiment, flow task or endpoint. Any artifacts and assets that are created during the job (models, datasets, plots, and so on) will be stored using cnvrg's file system and will be associated with the job for future reference.
# Linking your Git repo with a cnvrg project
Go to your project Settings tab, and find the Git Integration tab. Here, set the Git Repo and the Git Branch. You will need to specify if the repo is private or not.
There are two ways to authenticate cnvrg with Git to use your private repositories:
- SSH public and private key pair (done per project)
- OAuth token (done per user)
You cannot link an empty git repository. Ensure you have a branch before connecting.
# SSH public and private key pair
You will need to generate and SSH public and private key pair. The public key is given to the Git repository and the private key should be entered into cnvrg. Make sure you do not create a key that uses a password.
Navigate to the Git Integration tab of your project settings. After clicking Private Repo enter your SSH private key in the corresponding box.
Ensure the private key does not include a passphrase and that you have entered it with the following format:
-----BEGIN RSA PRIVATE KEY----- ... -----END RSA PRIVATE KEY-----
Click Save and your project will now clone your private Git repository when running jobs.
Here are a few links to instructions from major Git services explaining how to generate SSH keys:
You will need to generate a new pair for every Git repository you are linking with cnvrg.
When you enter the Git repo link in the project settings, you need to use the SSH format.
# OAuth token
You can authenticate your cnvrg account with your Git account using an OAuth token by adding it to your cnvrg account settings.
Navigate to your cnvrg account settings. Enter the OAuth token in the corresponding Git Access Token field. Click Save. Now your cnvrg account will be able to access all the same Git repositories that your Git account has access to.
You will still need to link the cnvrg project to the Git repository in its Settings. Navigate to the Git Integration tab in the project settings to do so.
Here are a few links to instructions from major Git services explaining how to generate OAuth tokens:
This will allow your cnvrg account access to all the private repos your Git account has access to.
When you enter the Git repo link in the project settings, you need to use the
# Saving artifacts when using Git
To track a jobs artifacts (for example, notebook checkpoints, experiment outputs and so on) you must indicate to cnvrg where to locate the artifacts your code produces.
When running the job, indicate to cnvrg what directory your code is saving the files to. The default is
output in the projects's home directory.
For example, if your code saves outputs like this:
Then make sure you select
artifacts as your output folder.
Make sure the Output dir matches what is in your code, otherwise cnvrg will not be able to track your artifacts.
Making collaboration simpler is a key goal in cnvrg's mission. As such, every project in cnvrg can have different members. Projects are private by default and only their collaborators can access them.
To view, add or remove collaborators from your project, go to the Settings tab of the project and click the Collaborators menu item.
More details on how collaboration works in cnvrg can be found here.
# Add a collaborator
To add a collaborator to the project:
- Go to Project > Settings > Collaborators.
- Click the Add Collaborator drop-down list.
- Type the username or email of the person you wish to add, or choose the user from the list.
- Click Save.
cnvrg adds the user as a collaborator on the project.
# Remove a collaborator
To remove a collaborator from the project:
- Go to Project > Settings > Collaborators.
- Click the Remove button next to the user you wish to remove.
cnvrg removes the user from the project.
Administrators in your organization have access to all projects, without being added as a collaborator.
# Project Settings
For each project in cnvrg, you can configure many different settings. You can access the project settings via the Settings tab on your project's sidebar. Below, you can see descriptions for each section.
# General Settings
- Name: The name of the project (Note: you can't change the name after the project is created.)
- Description: The description of the project.
- Privacy: The project can be set as private or public.
- Delete Project: Allows you to delete the project (Note: you are not able to recover deleted projects.)
- Image: Add a default docker image to your project.
- Compute: Set a default compute template or templates to run your jobs on.
- Command To Execute: Set a default command for experiments in the project.
- Working Directory: Set the default working directory for experiments. The command to be executed will be called inside the chosen working directory.
- Environment Variables: Key value pairs to be exported as environment variables.
- Run Tensorboard automatically: If enabled, the TensorBoard will start running automatically when a job is started.
- Restart when idle: cnvrg will restart experiments that haven't printed new logs for more than predefined time (The default is 60 minutes)
- Autosync: Turn on or off to perform periodic automatic sync.
- Sync Time: The duration for each autosync.
- On Spot Termination: If set to on, when you lose access to a spot, cnvrg will sync the experiment & restart it running on on-demand.
- Use single deploy api key: Use one set of keys when publishing endpoints in the project.
- Email notifications: Set the default settings for whether or not to send email notifications when an experiment finishes successfully or encounters an error.
- Webhooks - webhooks in cnvrg are a method for augmenting or altering the behavior of a web page, or web application, using custom callbacks. These callbacks may be maintained, modified, and managed by third-party users and developers who may not necessarily be affiliated with the originating website or application.
- Slack integration - Specify the name of your slack channel, and get real-time alerts on experiments.
# Slack Integration
cnvrg has the ability to send experiment notifications to a slack user or channel. This can help you keep up to date with the status of your running experiments.
# Project Secrets
Secrets are encrypted environment variables that you create in your project and are attached to each job that you run in the project.
# Creating a Secret
Go to your project Settings tab, and find the Secrets tab. Here, click on Add new secret and fill in the Secret key and Secret value.
The following rules apply to secret keys and values:
- Secret keys can only contain alphanumeric characters ([a-z], [A-Z], [0-9]) or underscores (_). Spaces are not allowed.
- Secret keys must not start with a number.
- Secret keys must be unique.
- Secret value is limited too 253 chars
# Accessing your secrets
Secrets will be available in every job that you run in the project, using environment variables:
- Jobs that are executed on a Kubernetes cluster, secrets will be mounted as Kubernetes Secrets
- Jobs that are executed on a Machine, secrets will be mounted as docker environment variables
For example, in a python code you can access a secret key named "AWS_ACCESS_KEY" in the following way:
import os os.environ.get("AWS_ACCESS_KEY")