Installing on ubuntu
Installing & configuring Docker¶
Some servers will come with Docker and docker-compose. You can test if your system has both installed by running:
docker --version
docker-compose --version
If this is not the case, you can follow the guidance on this page to get it up and running easily.
Install Docker¶
To install Docker on Ubuntu, please follow the official installation guide. The recommended method is using an apt repository.
Uninstall old versions on Ubuntu
If you've installed Docker using Ubuntu's official apt repositories, you must uninstall it and follow the above recommended procedure. These versions tend to be old and cause compatibility issues.
Configure Docker¶
Once installed, you can configure Docker by following the optional post-installation steps. We recommend you to follow the guide to manage Docker as a non-root user. This way you'll avoid having to run every docker
command as root and the developer experience will be more pleasant. You should also configure Docker to start on boot.
Install Compose¶
We rely heavily on docker-compose
to easily create reproducible development and test environments. The easiest way to install Compose on Ubuntu is to download the executable and place it somewhere on the PATH
as the official guide suggests. You can also install docker-compose
using pip with:
pip install docker-compose
Load the boidas
docker image¶
If you've received the Boidas release as a .zip package, please extract the Docker image (a .tar
file named Boidas-DockerImage-<version>.tar
) somewhere on your machine and run:
docker load -i Boidas-DockerImage-<version>.tar
(change the version as needed)
You should see the following message:
Loaded image: boidas:<version>
The image is now ready to be used on your local deployment.
Deploy Boidas¶
1. Create and configure docker-compose file¶
Create a file named boidas.yml
with the following content:
---
version: '2.1'
services:
pgsql-boidas:
image: postgres:15.5
container_name: pgsql-boidas
environment:
POSTGRES_DB: boidas
POSTGRES_USER: boidas
POSTGRES_PASSWORD: boidas
PGDATA: /var/lib/postgresql/data/pgdata
volumes:
- ./vols/pgdata:/var/lib/postgresql/data/pgdata
boidas-service:
image: "${DOCKER_REGISTRY_IP:PORT}/boidas:${BOIDAS-SERVICE_VERSION}"
container_name: boidas-service
restart: always
depends_on:
- pgsql-boidas
environment:
TZ: Europe/Madrid
DB_HOST: pgsql-boidas
DB_USER: boidas
DB_PASS: boidas
DB_NAME: boidas
WORKERS: 1
ENABLE_SSL: "TRUE"
MIGRATIONS: "yes"
VALIDAS_URL: ${VALIDAS_URL:-https://api.eu.veri-das.com/validas/v1}
API_KEY: ${API_KEY:-apikey_here}
BASE_URL: 'https://localhost:8443'
EMAIL_HOST_NAME: 'smtp.mycompany.com'
EMAIL_HOST_PORT: '587'
EMAIL_HOST_USER: "noreply@reply.com"
EMAIL_HOST_PASSWORD: "pass_here"
DEFAULT_FROM_EMAIL: "info-noreply@veridas.com"
LOG_INTEGRITY_KEY: "/var/keys/public_key.pem"
volumes:
- ./vols/media:/opt/boidas_backend/media
- ./vols/logs:/var/log/boidas
- ./vols/keys:/var/keys
boidas-nginx:
image: "${DOCKER_REGISTRY_IP:PORT}/boidas:${BOIDAS-SERVICE_VERSION}"
environment:
SERVER_NAME: localhost
NGINX_UPSTREAM: boidas-service
PORT: 8850
command: /opt/boidas_backend/run_nginx.sh
depends_on:
- boidas-service
ports:
- 8443:8443
volumes:
- ./vols/certs:/etc/boidas/security/certs/
This docker-compose creates:
- a service to access the Boidas web interface (on port
8443
). - a deployment that runs a group of containers: Boidas API (
boidas-api
), a web server for static content (boidas-nginx
) and a PostgreSQL database (boidas-postgresql
). - volumes for Boidas media (validation images, videos, etc.), service logs and PostgreSQL data.
You may want to customize the following environment variables for the boidas-api
container:
VALIDAS_URL
: The URL to the Validas instance to fetch validations from. By default this points to the VeriSaaS sandbox environment (work
)API_KEY
: Your API key for VeriSaaS on the environment (e.g.work
) corresponding toVALIDAS_URL
2. Running service¶
For running the docker-compose file (boidas.yaml
) defined on the previous step, the following command has to be executed.
docker-compose pull # Just if the images are in a docker registry
docker-compose -f docker-compose.yml up --abort-on-container-exit --force-recreate
3. Ensure boidas is running and get login credentials¶
After running, you can check that the dockers are running with:
docker ps
The expected output should be:
CONTAINER ID IMAGE NAMES COMMAND CREATED STATUS PORTS
6c696b965c boidas-<version> boidas-service "opt/boidas_backend..." X hours ago Up X hours 8080/tcp, 8443/tcp, 8850/tpc
2357487543 boidas-<version> boidas-nginx "supervisord -c /ect..." X hours ago Up X hours 8080/tcp, 8850/tpc, 0.0.0.0:8443->8443
4575cf4378 postgres:15.5 pgsql-boidas "/docker-entrypoint..." X hours ago Up X hours 5432/tcp
(the container d will change with every deployment)
You can view the logs from the boidas API with:
docker logs boidas-service
The first time, the boidas-api
container will initialize the database and create a default admin user and OAuth credentials. You can find them on the output from the command above. For example:
create_credentials
BOI-DAS SUPERUSER: admin
BOI-DAS SUPERUSER EMAIL: it@veridas.com
BOI-DAS SUPERUSER PASSWORD: 4ucSchV4PnzVM0ZYRLqFGrVs
BOI-DAS API SUPERUSER: admin
BOI-DAS API OAUTH2 CLIENT_ID: ISXyFVNqvuwMXkDcOblTDLf8
BOI-DAS API OAUTH2 CLIENT_SECRET: uGIQe3vnxMU90zMaxXanMVa47oRFHUB6qXaUdwDe2NTOBLze
Save these credentials, you'll use them later to login to Boidas.
4. Access the service¶
You can open the URL https://localhost:8443
on your favorite browser to navigate to the Boidas login page.
Note: Since Boidas uses self-signed HTTPS certificates by default, your browser will ask you to accept the security exception before showing the page.
You can login with the credentials (BOI-DAS SUPERUSER
/BOI-DAS SUPERUSER PASSWORD
) obtained from the boidas-api
container logs on the previous step of this guide.