Development Environment

Before contributing to CDS, you’ll need to install your development environment.

If you are familiar with these different tools, you probably will not need to read this page :-)


Download PostgreSQL from, version >= 9.6. Version 14.0 recommanded

You can easily use only PostgreSQL binaries, downloaded from

Initialize DB by running:

$ mkdir -p ~/data/postgres/data
$ initdb -D ~/data/postgres/data

Create user cds and database cds

$ psql -d postgres
postgres=# create user cds with password 'cds';
postgres=# create database cds owner cds;
postgres=# create database cdn owner cds;

Then launch PostgreSQL with:

$ postgres -D ~/data/postgres/data

Note: this is not recommended for a production installation.

That’s all for a local PostgreSQL installation


Download the latest stable Redis from, version >= 3.2

Example with version 4.0.11:

$ wget
$ tar xzf redis-4.0.11.tar.gz
$ cd redis-4.0.11
$ make
# launch redis-server
$ src/redis-server
# you should add src/ to your PATH

That’s all for a local Redis installation.


Download the latest stable Node.js from, version >= 16.4.2

Example with version 16.4.2 on macOS:

$ curl -O
$ tar xzf node-v16.4.2-darwin-x64.tar.gz
# directory node-v16.4.2-darwin-x64 is created
# You should add node-v16.4.2-darwin-x64/bin to your PATH


Download the latest Golang version from, version >= 1.18

Example with version 1.18 on macOS:

$ export GOROOT=~/go
$ export PATH=$PATH:$GOROOT/bin
$ cd ~
$ curl -O
$ tar xzf go1.18.darwin-amd64.tar.gz

Check if Go installation is ok

$ go version
go version go1.18 darwin/amd64


Compile CDS:

# Checkout code
$ mkdir -p $(go env GOPATH)/src/
$ cd $(go env GOPATH)/src/
$ git clone

# Compile everything
$ cd $(go env GOPATH)/src/
$ make clean # useful if you had already compile CDS before
$ make build

# if you want to build only one OS/ARCH, you can do for linux/amd64:
$ make build OS="linux" ARCH="amd64"

All binaries are stored in the dist/ directory

Configure CDS:

# Generate default configuration file
$ engine config new > ~/.cds/dev.toml

# edit ~/.cds/dev.toml file 
## in section [api]
### --> set variable defaultOS to your OS, darwin if you are on macOS for example

## in section [hatchery.local.commonConfiguration]
### --> set name to "hatchery-local"

## in section [hatchery.local.commonConfiguration.api.http]
### --> uncomment url, should be set to url = "http://localhost:8081" 

## in section [hatchery.local]
### basedir = "/tmp/cds" 
# this directory will contains the cds workers workspace

## in section [api.directories]
### baseDirectory = "/your-gopath/src/" 
# this directory should contains the workers binaries

## in section [api.artifact.local]
# baseDirectory = "/tmp/cds/artifacts"

Prepare database:

This command will create tables, indexes and initial data on CDS database. you have to launch it each time you have to upgrade cds.

$ cd $(go env GOPATH)/src/
$ engine database upgrade --db-password cds --db-sslmode disable

If you don’t have a local PostgreSQL, you should run engine database upgrade --help and update ~/.cds/dev.toml file.

Launch CDS engine API:

$ engine --config ~/.cds/dev.toml start api

Launch CDS UI:

$ cd $(go env GOPATH)/src/
$ npm start

Register first user with cdsctl:

# INIT_TOKEN is used to create the first user as an administrator of CDS.
export INIT_TOKEN=`./engine config init-token --config ~/.cds/dev.toml`
$ cdsctl signup -H http://localhost:8081 --email your-username@localhost.local --fullname yourFullname --username your-username
# Check CDS API logs to get the validation code

Launch local hatchery:

$ engine --config ~/.cds/dev.toml start hatchery:local

Open a browser, go on http://localhost:8080 - Have fun.


If you want to launch uService on different process:

# launch API only
$ engine --config ~/.cds/dev.toml start api

# launch local hatchery only
$ engine --config ~/.cds/dev.toml start hatchery:local

If you want to launch vcs & hooks ┬ÁServices, you have to:

Of course, you have to do the same thing with other ┬ÁServices repositories, elasticsearch, hatchery.swarm, etc…

A remark / question / suggestion, feel free to join us on