renku init

Create an empty Renku project or reinitialize an existing one.

Description

Use existing renku templates, either official or from the community, to create a new Renku project or Renku-ize an existing one.

Commands and options

renku init

Initialize a project in PATH. Default is the current path.

renku init [OPTIONS] [PATH]

Options

-n, --name <name>: Provide a custom project name.

--description <description>: Provide a description for the project.

-k, --keyword <keyword>: List of keywords.

--datadir <datadir>: Data directory within the project

-t, --template-id <template_id>: Provide the id of the template to use.

-s, --template-source <template_source>: Provide the templates repository url or path.

-r, --template-ref <template_ref>: Specify the reference to checkout on remote template repository.

-p, --parameter <parameters>: Provide parameters value. Should be invoked once per parameter. Please specify the values as follow: –parameter “param1”=”value”

-m, --metadata <metadata>: Custom metadata to be associated with the project.

-l, --list-templates: List templates available in the template-source.

-d, --describe: Show description for templates and parameters

--force: Override target path.

--initial-branch <initial_branch>: Initial git branch to create.

--external-storage, -S, --no-external-storage: Use an external file storage service.

Arguments

PATH: Optional argument

Use a different template

Renku is installed together with a specific set of templates you can select when you initialize a project. You can check them by typing:

$ renku template ls

INDEX ID     DESCRIPTION                     PARAMETERS
----- ------ ------------------------------- -----------------------------
1     python The simplest Python-based [...] description: project des[...]
2     R      R-based renku project with[...] description: project des[...]

If you know which template you are going to use, you can provide its id using --template-id.

You can use a newer version of the templates or even create your own one and provide it to the init command by specifying the target template repository source --template-source (both local path and remote url are supported) and the reference --template-ref (branch, tag or commit).

You can take inspiration from the official Renku template repository

$ renku init --template-ref master --template-source \
https://github.com/SwissDataScienceCenter/renku-project-template

Fetching template from
https://github.com/SwissDataScienceCenter/renku-project-template@master
... OK

NUMBER ID             DESCRIPTION                PARAMETERS
----- -------------- -------------------------- ----------------------
1     python-minimal Basic Python Project:[...] description: proj[...]
2     R-minimal      Basic R Project: The [...] description: proj[...]

Please choose a template by typing the number:

Provide parameters

Some templates require parameters to properly initialize a new project. You can check them by listing the templates renku template ls --verbose.

To provide parameters, use the --parameter option and provide each parameter using --parameter "param1"="value1".

$ renku init --template-id python-minimal --parameter \
"description"="my new shiny project"

Initializing new Renku repository... OK

If you don’t provide the required parameters through the option -parameter, you will be asked to provide them. Empty values are allowed and passed to the template initialization function.

Note

Project’s name is considered as a special parameter and it’s automatically added to the list of parameters forwarded to the init command.

Provide custom metadata

Custom metadata can be added to the projects knowledge graph by writing it to a json file and passing that via the –metadata option.

$ echo '{"@id": "https://example.com/id1", \
    "@type": "https://schema.org/Organization", \
    "https://schema.org/legalName": "ETHZ"}' > metadata.json

$ renku init --template-id python-minimal --parameter \
"description"="my new shiny project" --metadata metadata.json

Initializing new Renku repository... OK

Update an existing project

There are situations when the required structure of a Renku project needs to be recreated or you have an existing Git repository for folder that you wish to turn into a Renku project. In these cases, Renku will warn you if there are any files that need to be overwritten. README.md and README.rst will never be overwritten. .gitignore will be appended to to prevent files accidentally getting committed. Files that are not present in the template will be left untouched by the command.

$ echo "# Example\nThis is a README." > README.md
$ echo "FROM python:3.10-alpine" > Dockerfile
$ renku init

NUMBER  ID              PARAMETERS
-------  --------------  ------------
    1  python-minimal  description
    2  R-minimal       description
    3  bioc-minimal    description
    4  julia-minimal   description
    5  minimal
Please choose a template by typing the number: 1
The template requires a value for "description": Test Project
Initializing Git repository...
Warning: The following files exist in the directory and will be overwritten:
        Dockerfile
Proceed? [y/N]: y
Initializing new Renku repository...
Initializing file .dockerignore ...
Initializing file .gitignore ...
Initializing file .gitlab-ci.yml ...
Initializing file .renku/renku.ini ...
Initializing file .renkulfsignore ...
Overwriting file Dockerfile ...
Initializing file data/.gitkeep ...
Initializing file environment.yml ...
Initializing file notebooks/.gitkeep ...
Initializing file requirements.txt ...
Project initialized.
OK

If you initialize in an existing git repository, Renku will create a backup branch before overwriting any files and will print commands to revert the changes done and to see what changes were made.

You can also enable the external storage system for output files, if it was not installed previously.

$ renku init --external-storage