Skip to content

IT system requirements#

All our applications are open Source (Python/Django) working on Linux (preferably Ubuntu). In terms of hardware, the system should have 16GB RAM and cpu 3 GHz. Ideally there should be two machines with these criteria, one of the web server and one for the database.

Setup a dev environment#

A running local instance for development can be spun up via docker compose which will install and configure all deps in separate containers. As such your computer should only need:

If docker compose give you trouble, make sure it can connect to the docker daemon.

If you use an Apple Silicon Mac, ensure export DOCKER_DEFAULT_PLATFORM=linux/amd64 is set.

A pgdata-iaso folder, containing the database data, will be created in the parent directory of the git repository.

Environment variables#

The docker-compose.yml file contains sensible defaults for the Django application.

Other environment variables can be provided by a .env file.

As a starting point, you can copy the sample .env.dist file and edit it to your needs.

cp .env.dist .env

Note: All the commands here need to be run in the project directory in which the repository was cloned.

Activate Polio plugin#

Add this to your .env file to activate the polio plugin:

PLUGINS=polio

Build the containers#

This will build and download the containers.

docker-compose build

Database dump#

To create a copy of your iaso database in a file (dump) you can use:

docker-compose exec db pg_dump -U postgres iaso  -Fc > iaso.dump

The dumpfile will be created on your host. The -Fc means it will use an optimized Postgres format (which takes less space). If you want the plain sql command use -Fp.

Start the database#

docker-compose up db

Run migrations#

docker-compose run --rm iaso manage migrate

If you get a message saying that the database iaso does not exist, you can connect to your postgres instance using

psql -h localhost -p 5433 -U postgres

then type

create database iaso;

to create the missing database.

Start the server#

To start all the containers (backend, frontend, db)

docker-compose up

The web server will be reachable at http://localhost:8081.

The docker-compose.yml file describes the setup of the containers.

Create a superuser#

To login to the app or the Django admin, a superuser needs to be created with:

docker-compose exec iaso ./manage.py createsuperuser

You can now login in the admin at http://localhost:8081/admin.

Then additional users with custom groups and permissions can be added through the Django admin or loaded via fixtures.

Create and import data#

To create the initial account, project and profile, do the following:

docker-compose exec iaso ./manage.py create_and_import_data

You can now login on http://localhost:8081 but still need to import your own data.

Restore database from dump#

Ensure the database server is running but not the rest. Close your docker compose, ensure it is down with 

docker-compose down

Launch the database server with

docker-compose up db

Choose a name for your database. In this example it will be iaso5.

You can list existing databases using:

docker-compose exec db psql -U postgres -l

Create the database:

docker-compose exec db psql -U postgres -c "create database iaso5"

Restore the dump file to put the data in your database:

cat iaso.dump | docker-compose exec -T db pg_restore -U postgres -d iaso5 -Fc --no-owner /dev/stdin

Edit your .env file to use to this database in the RDS_DB_NAME settings.

Start Iaso. Cut your docker compose (see 0) and relaunch it fully. Warning: Modification in your .env file are not taken into account unless you entirely stop your docker compose

Health#

On the /health/ url you can find listed the Iaso version number, environment, deployment time, etc... that might help you understand how this server instance is deployed for debugging. E.g. https://www.poliooutbreaks.com/health/

Live Bluesquare components#

It is possible to configure the project to load a version of Bluesquare components from a local git repository instead of the one installed from a package.

This enabled the development of features necessitating modification in the components code.

To do so:

  • place the repository in the parent repository of Iaso ../bluesquare-components/
  • install the dependency for bluesquare-component by running npm install in its directory
  • set the environment variable LIVE_COMPONENTS=true
  • start your docker compose
cd ..
git clone git@github.com:BLSQ/bluesquare-components.git
cd  bluesquare-components
npm ci
cd ../iaso
LIVE_COMPONENTS=true docker-compose up

This way the page will reload automatically if you make a change to the bluesquare-components code.

This functionality also works if you launch webpack outside of docker.

If you encounter any problem, first check that your repo is on the correct branch and the deps are up-to-date

Task worker#

In local development, you can run a worker for background tasks by using the command:

docker-compose run iaso manage tasks_worker

Alternatively, you can call the url tasks/run_all which will run all the pending tasks in queue.

Customization#

You can override default application title, logo and colors using the .env file and specify those variables:

THEME_PRIMARY_COLOR="<hexa_color>"
THEME_PRIMARY_BACKGROUND_COLOR="<hexa_color>"
THEME_SECONDARY_COLOR="<hexa_color>"
APP_TITLE="<app_title>"
FAVICON_PATH="<path_in_static_folder>"
LOGO_PATH="<path_in_static_folder>"
SHOW_NAME_WITH_LOGO="<'yes' or 'no'>"

Those settings are optional and are using a default value if nothing is provided

Start adding features#

You can now start to develop additional features