This article is only valid for 2.3 or later.

This documentation page tries to clear up questions regarding Portus and the database. If this page is not clear enough, please submit a new issue or ask on our official mailing list.

For further documentation you can also check out some of the examples.

Supported database backends

You could theoretically use any database with Portus, but we have decided on two choices: MariaDB (default) and PostgreSQL. In order to support other RDBMS we would need to add them in the Gemfile and call bundle, which is a burden in containerized scenarios.

You can pick the adapter with the PORTUS_DB_ADAPTER environment variable, which defaults to mysql2. For PostgreSQL you need to set it to postgresql.

Support for these adapters require two gems that have to be built natively:

  • mysql2: this gem needed for MariaDB needs the development files for MySQL in order to be installed properly. For openSUSE, these come with the libmysqlclient-devel package.
  • pg: for PostgreSQL you will need to install the development files for PostgreSQL. For openSUSE, these come with the postgresql-devel package.

Note that these dependencies have already been bundled in the official Portus image.

Configuration options

In order to connect to the database, Portus requires more environment variables. The most important ones being:

  • PORTUS_DB_HOST: the location of your database. It defaults to localhost.
  • PORTUS_DB_USERNAME: the name of the user accessing the database for Portus. It defaults to root.
  • PORTUS_DB_PASSWORD: the password to be used when accessing the database. It defaults to an empty string.

Besides this, you can further configure this with other options:

  • PORTUS_DB_PORT: an alternative port for the database.
  • PORTUS_DB_POOL: the number of pool connections.
  • PORTUS_DB_TIMEOUT: the timeout for requests.

When not provided, the options above take the default value of the database backend.

Last but not least, the name of the database will be portus_$environment. So, for a production environment, it will be portus_production. That being said, you can provide another name with the PORTUS_DB_DATABASE environment variable.

How Portus bootstraps the database

Portus is a Ruby on Rails application, and as such, it connects to the database through a given config/database.yml. This file is filled with the environment variables documented in the previous section. At this point, Portus is able to talk to the database, but it has to first sync the schema before doing anything with it. In order to do so, the usual commands from a Ruby on Rails application are:

$ bundle exec rake db:create
$ bundle exec rake db:migrate
$ bundle exec rake db:seed

If you have installed Portus through the RPM or you are using the official Portus image, you can call portusctl instead of bundle in order to get the right environment (otherwise you can simply use /srv/Portus as the working directory).

For the containerized scenario though, you have to wait for the database to be up. You can do this in two ways:

  1. Manually (not recommended): in the Portus source code there is an executable script that can check whether the DB is up. You can call it like this: portusctl exec rails r bin/check_db.rb.
  2. Init script: if you are using tools/frameworks such as docker-compose, Docker Swarm, Kubernetes, etc. you cannot manually check for the database. Instead, you should create your own init script for your container. In the source code of Portus, you can find some examples on the examples directory. A possible script would be the following:
#!/usr/bin/env bash

while true; do
    if bundle exec rake db:migrate:reset; then
        bundle exec rake db:seed
        break
    fi

    echo "Waiting for mariadb to be ready in 5 seconds"
    sleep 5
done

pumactl -F /srv/Portus/config/puma.rb start

Considerations when deploying a database for Portus

Portus does not require anything specific for the database. Thus, you can deploy your database cluster in the way you feel it’s safer, faster, etc.