udata setup instructions¶
This guide is about starting a udata and udata-front environment for local development.
We’ll use the following repositories:
Check the system requirements¶
Info
Be aware that udata now requires Python >3.7 to work.
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
Warning
If you have no output at all for too long, check the IPv6 possible issue.
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.
Info
You need to make sure that your virtualenv is activated for the entire development process.
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
Info
You now have a working udata instance but no frontend for the platform.
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.
Info
udata and udata-front use different node versions so don’t forget to run nvm use
when you switch from one to the other.
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
Tell us what you think
You are always welcome to tell us about your experience installing udata. Get in touch with us by raising a new issue on GitHub.
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.