Docker Compose

NuoDB installed with a Limited Use License on a single host Docker environment is suitable for product evaluation and Dev / Test use only. NuoDB does not support production deployments in Docker environments. To obtain a Limited Use License key, contact NuoDB Support.

Introduction

Docker Compose makes it easy to run a preconfigured arrangement of containers. You specify the container or containers you want to run in a YAML definition file.

NuoDB offers several compose options in a public Github project: http://github.com/nuodb/nuodb-compose. Here we discuss two of those options:

  1. Running everything (one AP, one TE and one SM) in a single "monolith" container.

  2. Running each process in its own container on a docker defined sub-network, similar to the previous Docker Quick Start.

In most cases, the "monolith" option is sufficient for development and testing on a local machine.

Setup

This is typically a one-off setup. In general the only things you may need to change later are the NuoDB version, database name, username and password.

  1. For NuoDB 6.0.x and later, contact NuoDB Support to obtain the license file required to deploy NuoDB with a Limited Use License. This may take 1-2 business days.

    • Please supply your name, your company or 3DS brand, the project/service you are working on and how long the license should last.

    • Alternatively, use NuoDB 5.x.x that comes with comes with a built-in limited license and can be used immediately.

  2. Install Docker into your RHEL / CentOS, MacOS, or Windows environment.

  3. Make sure you have git installed on your machine, or, open http://github.com/nuodb/nuodb-compose in your browser and use the Download ZIP option.

    • Using git clone is better as you can easily pull down updates as they occur.

    • Click the green <> Code button to see the URL for git clone or to get the ZIP download.

      github docker compose code button

  1. Create a local copy.

  2. Open a CMD, Powershell or Terminal window.

  3. Make your cloned nuodb-compose your current directory: cd /path/to/nuodb-compose.

  4. Change into the nuodb sub-directory: cd nuodb.

  5. Copy env-default to .env.

  6. If using NuoDB 6.0.x or later, save the license file to a local file, such as nuodb.lic.

  7. Edit .env using your favorite editor.

  8. Set LICENSE_PATH=/path/to/nuodb.lic.

    • You do not need to do this to run any NuoDB version 5 image (it has a built-in limited license).

  9. At the very bottom of the file, uncomment and set EXTERNAL_ADDRESS=127.0.0.1.

    • This allows you to access the database from applications running on your local machine as if NuoDB was installed directly onto it.

    • To access the database from a different computer, set EXTERNAL_ADDRESS to the IP address of your machine.

      • However, if this IP address changes you will need to restart with a new address and you will lose your database unless you have a backup (see below).

  10. Set the NUODB_IMAGE.

    • To use the latest, simply set NUODB_IMAGE=nuodb/nuodb-ce:latest (you will need a license).

    • To see what images are available open https://hub.docker.com/search?q=nuodb in your browser.

      • Click into nuodb/nuodb.

      • All the images and their tags are on the Tags tab.

  11. Optionally change DB_NAME, DB_USER and/or DB_PASSWORD if you wish.

  12. Save .env.

Running a Single Container

  1. To run the monolith (all-in-one) container we recommend adding the version name into the container name using the -p option. The -d detaches the container process to run in the background.

    docker compose -p <version> -f monolith.yaml up -d

    • For example to run version 6.0.2: docker compose -p v6.0.2 -f monolith.yaml up -d

  1. Check it is running (output here is split across multiple lines for readability):

    docker ps
CONTAINER ID  IMAGE                  COMMAND                 CREATED      STATUS
5ccf1e6ff12d  nuodb/nuodb-ce:6.0.2   "docker-entrypoint.s…"  2 mins ago  Up 2 mins

PORTS
0.0.0.0:8888->8888/tcp, :::8888->8888/tcp, 0.0.0.0:48004-48006->48004-48006/tcp, :::48004-48006->48004-48006/tcp

NAMES
v602-monolith-1

  • The container name is <version>-monolith-1, in this case v602-monolith-1.

  • Note the port mappings. The AP is available on localhostL48004 and localhost:8888, the SM on localhost:48005 and the TE on localhost:48006. These are all NuoDB’s usual default ports.

Access and Management

  1. You can now access the database from your application.

    • For example, if you left the database name as demo, a JDBC application would use the URL jdbc:com.nuodb://localhost/demo.

  2. To run nuosql or nuocmd you need to use docker exec. For example:

    • nuocmd: docker exec -it v602-monolith-1 nuocmd show domain

    • nuosql: docker exec -it v602-monolith-1 nuosql demo --user dba --password dba

    • Or run a bash shell in the container: docker exec -it v602-monolith-1 bash

      • Once bash is running you can look at files in the container, such as logs, configuration files and your archive.

      • The bash session will run until you enter CTRL-D or exit.

  3. To manage the container:

    • Stop the database using docker compose -p v602 stop and restart it using docker compose -p v602 start. The database archive is kept if you do this.

    • To view logs: docker logs v602-monolith-1 (outputs nuoadmin.log to the console).

    • When you no longer need the container, delete it with docker compose -p v602 down. This destroys the container and the database archive.

    • For more on managing containers see the project README.

A nice feature of using docker compose is that it is easy to use different versions of NuoDB.

  1. Edit .env again and change the NUODB_IMAGE to point to the version you want.

  2. Make sure any previous containers are stopped (or you will get a port conflict).

  3. Run docker compose -p <new-version> -f monolith.yaml up -d using the new version.

  4. You can stop the container at any time, keeping it until you need it again.

Other Options

Multiple Containers

To run a different container for each NuoDB process, use the distributed setup.

The monolith is easiest to setup and use, but this distributed setup is useful if you want to test the effect of losing one of the processes on your application. You can also scale out to run a second TE for your tests.

$> docker compose -p v602 up -d
$> docker ps
CONTAINER ID  IMAGE         COMMAND         CREATED     STATUS
6e92b10ef71a  nuodb/nuodb-ce:6.0.2  "docker-entrypoint.s…"  5 seconds ago  Up 3 seconds
bb12f4f94f9e  nuodb/nuodb-ce:6.0.2  "docker-entrypoint.s…"  5 seconds ago  Up 3 seconds
2b82d39a6577  nuodb/nuodb-ce:6.0.2  "docker-entrypoint.s…"  5 seconds ago  Up 3 seconds

PORTS
8888/tcp, 48004-48005/tcp, 0.0.0.0:48006->48006/tcp, :::48006->48006/tcp
8888/tcp, 48004-48006/tcp
0.0.0.0:8888->8888/tcp, :::8888->8888/tcp, 0.0.0.0:48004-48005->48004-48005/tcp, :::48004-48005->48004-48005/tcp, 48006/tcp

NAMES
v602-te1-1
v602-sm-1
v602-nuoadmin1-1

  • Distributed configuration is the default so no -f option is required.

  • Again we use -p to prefix the version to the container names.

  • Although 3 different containers are running the process port mappings (and the connection string or URL) are the same.

Access and Management

Access and management is identical to above except that you now have 3 containers. In all cases specify the admin container:

For example:

  • nuocmd: docker exec -it v602-nuoadmin1-1 nuocmd show domain

  • nuosql: docker exec -it v602-nuoadmin1-1 nuosql demo --user dba --password dba

  • Or run a bash shell in the container: nuocmd: docker exec -it v602-nuoadmin1-1 bash

    • Once bash is running you can look at logs, configuration files and your archive.

    • The bash session will run until you enter CTRL-D or exit.

  • To view logs: docker logs v602-nuoadmin1-1 (outputs nuoadmin.log to the console).

    • Or specify v602-te1-1 or v602-sm-1 to see logs from the TE or SM respectively.

Backup and Restore

To backup your database, use nuocmd hotcopy:

  • Generate the backup and copy it locally:

    # Run a simple hotcopy (online) backup.
docker exec -it <container-name> nuocmd hotcopy database --db-name <db-name>> --type simple --backup-dirs 0 /tmp/demo-backup

# Wait for the back process to finish, then copy the file
docker cp <container-name>:/tmp/demo-backup .

  • Then compress the backup using tar -cz or 7zip to produce a compressed tar file.

To restore:

  • Edit .env and set IMPORT_LOCAL=/path/to/demo-backup.tar.gz.

  • Create your database (distributed or monolith) as described above.

If you keep your backup on a remote server with FTP or HTTP(S) access:

  • Edit .env and set IMPORT_REMOTE=sftp:/path/to/demo-backup.tar.gz.

    • http or https are also supported.

  • If a username and password are required for access, set IMPORT_AUTH=<username>:<password>

For more details on restoring from a backup, refer to https://github.com/nuodb/nuodb-compose#importing-existing-data.

More Information

Two other options are available:

  1. Running the distributed (three container) system with additional containers running NuoDB Insights.

  2. The instadb configuration runs a monolith setup but maps the NuoDB processes to random ports on your local machine. This is useful if you need to run multiple databases or multiple version at the same time.

    • The output from docker ps will show you the mapping for port mapping for 48006 (the TE port).

    • You then need to use a direct connection to localhost:<port> to access the TE for each database as described here.

For more information, refer to the project README