Deploying with an external database instance
You can deploy analyze-containers to connect to a database instance that is not managed by analyze-containers. When you deploy analyze-containers it can create and manage the database, but it does not manage the database instance.
The configuration that determines if an external database instance is per config.
The prerequisites for an external database instance:
- The external database must be able to communicate with the analyze-containers containers on the
eia
Docker network and the containers must be able to communicate with it. - Provide a username and password for an admin user in the external database instance. This user must be able to create databases and other database users required by the deployment.
Configuring the connection to the external database instance
Edit the
configs/<config-name>/utils/variables.conf
file to provide the required information.Variable Description DB_USER_MANAGED
Can be set to true
orfalse
. If set totrue
, analyze-containers does not manage the database instance.DB_FQDN
The fully qualified domain name of the database instance. DB_PORT
The port number to connect to the database instance. DB_SSL_CONNECTION
Can be set to true
orfalse
. If set tofalse
then traffic to/from the instance will be sent in clear text. If set totrue
then traffic to/from the instance will be encrypted via SSL.DB_LOCATION_DIR
The location in the external database instance to create the database. DB_USERNAME
The username of the admin user in the external database instance. An example PostgreSQL configuration:
DB_USER_MANAGED="true" DB_FQDN="external-postgres.eia" DB_PORT="5432" DB_SSL_CONNECTION="true" DB_LOCATION_DIR="/var/lib/postgresql/data" DB_USERNAME="postgres"
An example SQL Server configuration:
DB_USER_MANAGED="true" DB_FQDN="external-sqlserver.eia" DB_PORT="1433" DB_SSL_CONNECTION="true" DB_LOCATION_DIR="/var/opt/mssql/data" DB_USERNAME="sa"
Note:
- If your external database is hosted in a Docker container on a different network to your config development environment, connect your external database container to the
eia
network. For example, rundocker network connect eia <external-database-container>
. - If your database is running on your host machine, use the
host.docker.internal
as theDB_FQDN
value.
- If your external database is hosted in a Docker container on a different network to your config development environment, connect your external database container to the
Provide the external database user's password.
Create the directory and file to store the password secret.
- For PostgreSQL:
configs/<config-name>/configuration/secrets/postgres/postgres_PASSWORD
- For SQL Server:
configs/<config-name>/configuration/secrets/sqlserver/sa_PASSWORD
- For PostgreSQL:
In the password file, provide the user's password.
The password is stored in plain text, do not store this file in source control.
Configure SSL.
If your external database uses SSL (you have
DB_SSL_CONNECTION="true"
) then the certificate must be one that the deployment "trusts". For security reasons, certificate verification is not optional; there is no "ignore verification and automatically trust all certificates" option.If your database's SSL certificate is not issued by a "well known" issuer (e.g. it is a self-signed certificate, or signed by a corporate internal CA rather than a public commercial provider) then you will need to provide the certificate(s) to the deployment so that the deployment knows to "trust" it:
- For a certificate that has been signed by an untrusted (self-signed or private) CA, add the (public part of the) CA certificate to
configs/<config-name>/configuration/secrets/additional-trust-certificates.cer
. - This file is a text file in OpenSSL PEM format, i.e. certificates should start "
-----BEGIN CERTIFICATE-----
". - Do NOT include the private key to the deployment. That should be private to your database (and only your database).
- For a certificate that has been signed by an untrusted (self-signed or private) CA, add the (public part of the) CA certificate to
Deploy the config using the
deploy
command in the usual way. For example:deploy -c <config-name>