udata setup instructions¶

This guide is about starting a udata backend and cdata (formerly udata-front) frontend environment for local development.

We’ll use the following repositories:

• udata - The backend API and core platform
• cdata - The frontend repository

Check the system requirements¶

udata requires several libraries to be installed to work. You can see them on the udata documentation link below.

We’ll use docker compose to manage external services so you don’t have to install native mongodb and redis.

Setup udata¶

udata requires a directory to contain the project, its plugins and all associated content. The recommended layout for this directory is displayed in the following schema. We’ll make all this together.

$UDATA_WORKSPACE
├── fs
├── udata
│   ├── ...
│   ├── pyproject.toml
│   └── udata.cfg
└── cdata
    └── ...

Get udata¶

Make a new directory. You can name it as you like:

mkdir udata-workspace
cd udata-workspace
export UDATA_WORKSPACE=`pwd`  # we'll use UDATA_WORKSPACE env in the instructions

In this new directory, clone udata:

git clone git@github.com:opendatateam/udata.git

You can start your local development environment with docker compose.

cd udata
docker compose up

Install virtual env and dependencies¶

With uv (recommended):

uv sync

…or with pip (requires pip 25.1+):

python3 -m venv .venv
source .venv/bin/activate
pip install --group dev -e .

You can find common errors and workarounds for MacOS on udata documentation.

Configure udata¶

udata uses a config file called udata.cfg and a custom directory as a base for its filesystem, we’ll call it fs. You can put them as shown below.

$UDATA_WORKSPACE
├── fs
└── udata
    ├── ...
    ├── pyproject.toml
    └── udata.cfg

A sample content of udata.cfg for local development is shown below.

from udata.settings import Defaults

# generate secrets with `python -c "import secrets; print(secrets.token_urlsafe(64))"`
SECRET_KEY='generated-secret'
API_TOKEN_SECRET='another-generated-secret'
ELASTICSEARCH_URL='http://localhost:9200'

HARVESTER_BACKENDS = ['dcat']
HARVEST_MAX_ITEMS = 100

DEBUG = True
SEND_MAIL = False
SERVER_NAME ='dev.local:7000'
CDATA_BASE_URL = 'http://localhost:3000'
CACHE_TYPE = 'flask_caching.backends.null'

URLS_ALLOW_PRIVATE = True
URLS_ALLOW_LOCAL = True
URLS_ALLOWED_TLDS = Defaults.URLS_ALLOWED_TLDS | set(['local'])

RESOURCES_FILE_ALLOWED_DOMAINS = ['*']
FS_ROOT = 'fs'

SESSION_COOKIE_SECURE = False

This defines dev.local:7000 as the URL for your local setup. You’ll have to edit your /etc/hosts (Linux) or C:\Windows\System32\drivers\etc\hosts (Windows) to add this rule.

127.0.0.1       dev.local

Running the project for the first time¶

You need to initialize some data before being able to use udata. The following command will initialize database, indexes, create fixtures, etc.

udata init

You can then start udata server with the serve subcommand.

inv serve

Now, you can use your udata API!

curl http://dev.local:7000/api/1/datasets/

You can see API endpoints by going to http://dev.local:7000/api/1/ in your browser.

Workers are required to execute tasks (search indexation, etc.).

With uv:

cd $UDATA_WORKSPACE/udata
uv run inv work

With pip (if not already activated):

cd $UDATA_WORKSPACE/udata
source .venv/bin/activate
inv work

Install cdata frontend (formerly udata-front)¶

With a valid udata environment, you can start the cdata installation:

$UDATA_WORKSPACE
├── fs
├── udata
│   ├── ...
│   ├── pyproject.toml
│   └── udata.cfg
└── cdata
    └── ...

First, clone cdata in your workspace.

cd $UDATA_WORKSPACE
git clone git@github.com:datagouv/cdata.git

Modify your udata.cfg with the following lines.

THEME = 'gouvfr'

The last thing to do is to install the frontend cdata packages using pnpm.

cd cdata
nvm install
nvm use

pnpm install

Once it’s done, you should be able to run the build commands for JavaScript and CSS in cdata. Check the cdata repository documentation for the specific build commands.

Start udata with cdata¶

To start udata, the inv command is the same.

cd $UDATA_WORKSPACE/udata
inv serve

You can now visit dev.local:7000/ in your browser and start playing with your udata instance.

For watching and building frontend assets, check the cdata repository documentation for the specific commands.

Other commands¶

You can rebuild the search index with the following command.

udata search index

Finally, you can see other administrative tasks in administrative-tasks

Going further¶

Once the project is up and running, it’s time to customize it! Take a look at our advanced documentation on adapting settings, extending udata, testing your code, adding translation and so on.