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://dev.local:3000'
CACHE_TYPE = 'flask_caching.backends.NullCache'

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

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.

uv run udata init

You can then start udata server with the serve subcommand.

uv run 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 asynchronous tasks (search indexation, etc.). Start one in another terminal:

cd $UDATA_WORKSPACE/udata
uv run inv work

Running udata without a frontend¶

You now have a working udata instance, without any frontend. This is enough for most testing needs, since everything udata does is reachable from the API and the command line:

# Browse and exercise the API
curl http://dev.local:7000/api/1/datasets/

# Create an API token from an account you own, then use it as a bearer token
curl -H "Authorization: Bearer <token>" http://dev.local:7000/api/1/me/

# Create a harvester and run it synchronously, as many times as you need
uv run udata harvest create dcat https://example.org/catalog.rdf "My harvester"
uv run udata harvest sources
uv run udata harvest run <source-id>

# Inspect the database with the models loaded
uv run udata shell

See administrative tasks for the other commands, API tokens to authenticate your calls and harvesting for the harvesters.

Install cdata below only if you need the web interface itself.

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

Then install its packages using pnpm.

cd cdata
nvm install
nvm use

pnpm install

Start udata with cdata¶

udata and cdata are two separate servers: udata no longer renders any page, it only serves the API that cdata calls. You need both running, each in its own terminal.

# Terminal 1: the udata API, on dev.local:7000
cd $UDATA_WORKSPACE/udata
uv run inv serve

# Terminal 2: the cdata frontend, on dev.local:3000
cd $UDATA_WORKSPACE/cdata
pnpm run build
pnpm run preview

By default cdata calls the API on http://dev.local:7000, which matches the SERVER_NAME set above. NUXT_PUBLIC_API_BASE is read when the server starts, not baked at build time, so you can point the same build at another instance:

NUXT_PUBLIC_API_BASE=http://dev.local:7001 pnpm run preview

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

Other commands¶

You can rebuild the search index with the following command.

uv run 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.