udata setup instructions¶

This guide is about starting a udata and udata-front environment for local development.

We’ll use the following repositories:

• https://github.com/opendatateam/udata
• https://github.com/etalab/udata-front

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
│   ├── ...
│   ├── setup.py
│   └── udata.cfg
└── udata-front
    ├── ...
    └── setup.py

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¶

udata uses pip to install its dependencies. You can create a virtualenv, activate it and install the requirements with the following commands.

python3 -m venv venv
source venv/bin/activate
pip install -r requirements/develop.pip
pip install -e .

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

Install nvm and dependencies¶

udata and udata-front use NVM to manage node versions (based on .nvmrc file). You can install it based on their instructions.

Then, you can install and activate the required node version.

nvm install
nvm use

You can install JavaScript dependencies with NPM.

npm install

Once it’s done, you should be able to run the build commands for JS and CSS.

inv assets-build
inv widgets-build

Configure udata¶

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

$UDATA_WORKSPACE
├── fs
└── udata
    ├── ...
    ├── setup.py
    └── udata.cfg

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

from udata.settings import Defaults

DEBUG = True
SEND_MAIL = False
SERVER_NAME ='dev.local:7000'
CACHE_TYPE = 'null'

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

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

This define dev.local:7000 as the URL for your local setup. You’ll have to edit your /etc/hosts 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 initalize 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 for tasks to execute (search indexation, etc.).

source $UDATA_WORKSPACE/udata/venv/bin/activate  # Make sure your virtualenv is activated
inv work

Install udata-front¶

With a valid udata environment, you can start the udata-front installation.

$UDATA_WORKSPACE
├── fs
├── udata
│   ├── ...
│   ├── setup.py
│   └── udata.cfg
└── udata-front
    ├── ...
    └── setup.py

First, clone udata-front in your workspace.

cd $UDATA_WORKSPACE
git clone git@github.com:etalab/udata-front.git

Modify your udata.cfg with the following lines.

PLUGINS = ['front']
THEME = 'gouvfr'

udata-front uses the same virtualenv as udata. You can activate it from your udata-front directory if it’s not the case anymore.

source $UDATA_WORKSPACE/udata/venv/bin/activate

Then, you can install pip requirements.

cd udata-front
pip install -e . -r requirements/test.pip -r requirements/develop.pip

The last thing to do is to install udata-front NPM packages.

nvm install
nvm use

npm install

Once it’s done, you should be able to run the build commands for JS and CSS.

inv assets-build

Start udata with udata-front¶

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.

You can use parcel to watch for file changes in udata or udata-front directory with

inv assets-watch 

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, creating a custom theme, extending udata, testing your code, adding translation, setting up a search service and so on.