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.
- -i, --template-index <template_index>
Deprecated
- -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
INDEX 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 index:
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.7-alpine" > Dockerfile
$ renku init
INDEX 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 index: 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