Docker

Quick Start Guide

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.

The following takes you through the steps to setup NuoDB using a different Docker container for each process, populating a database and accessing it using nuosql.

If you have not used NuoDB before, this quick-start tutorial gives you a good feel for how it all works. Alternatively, to get setup with NuoDB in Docker quickly for development, we recommend using docker-compose to do the setup for you.

Installation

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

To download or "pull" the latest NuoDB image from the nuodb repository on Docker Hub and install it on your local machine, use:

docker pull nuodb/nuodb:latest

Create a Docker Network

docker network create nuodb-net

Start the NuoDB Admin Service

Let’s name the NuoDB Admin Service "nuoadmin1" and let’s call the storage volume "nuoadmin-raft-1":

docker run -d --name nuoadmin1 --hostname nuoadmin1 \
   --network nuodb-net --publish 8888:8888 \
   --volume nuoadmin-raft-1:/var/opt/nuodb \
   --env NUODB_DOMAIN_ENTRYPOINT=nuoadmin1 \
   nuodb/nuodb:latest nuoadmin

The following command should show "nuoadmin1" as ACTIVE and the LEADER for the domain, but there’s no databases associated with the domain yet:

docker exec -it nuoadmin1 nuocmd show domain

/var/log/nuodb/nuoadmin.log is nuoadmin’s persistent log file. In case of problems, check the log file for issues.

Install a Limited Use License

To obtain the license file required to deploy NuoDB with a Limited Use License, contact NuoDB Support. To install the Limited Use License, run:

docker cp </path/to/local/nuodb.lic> nuoadmin1:/tmp/nuodb.lic
docker exec nuoadmin1 nuocmd set license --license-file /tmp/nuodb.lic

To obtain information about the effective license used, use nuocmd get effective-license.

For example:

docker exec -it nuoadmin1 nuocmd get effective-license

For more information, see Obtain and Install a Product License.

Start a Storage Manager (SM)

Start an SM to manage the database archive:

docker run -d --name test-sm-1 --hostname test-sm-1 \
  --network nuodb-net --volume test-arch-vol-1:/var/opt/nuodb/archive \
  nuodb/nuodb:latest \
     nuodocker --api-server nuoadmin1:8888 \
     start sm --db-name test --server-id nuoadmin1 \
     --dba-user dba --dba-password goalie

In the above example, the SM has been named "test-sm-1", the archive volume "test-arch-vol-1", and the database "test" with database login credentials of user "dba" with password "goalie", as we’ll be importing the sample ice hockey database later. The server-id is the name of the NuoDB Admin service we started earlier, "nuoadmin1".

The following command should now show that we’ve started an SM and have an (empty) database running:

docker exec -it nuoadmin1 nuocmd show domain

Start a Transaction Engine (TE)

Start a TE to handle SQL queries:

docker run -d --name test-te-1 --hostname test-te-1 \
  --network nuodb-net nuodb/nuodb:latest \
     nuodocker --api-server nuoadmin1:8888 \
     start te --db-name test \
     --server-id nuoadmin1

In the above example, the TE has been named "test-te-1" and it’s been associated with the empty database "test" and the server-id is the name of the NuoDB Admin service we started earlier, "nuoadmin1".

Import the Sample Ice Hockey Database

Open a bash shell session in the "nuoadmin1" container:

docker exec -it nuoadmin1 bash
As you are now in a bash shell in the "nuoadmin1" container, to see the status of the domain, you can simply run:
nuocmd show domain which shows the "test" database is now associated with the domain, has state = RUNNING with an SM and a TE process, and both are in the state MONITORED:RUNNING.

Use the following commands to import the sample ice hockey database schemas into the empty "test" database in the NuoDB Admin service container "nuoadmin1":

nuosql test@nuoadmin1 --schema hockey --user dba --password goalie \
</opt/nuodb/samples/quickstart/sql/create-db.sql >& /dev/null
nuosql test@nuoadmin1 --schema hockey --user dba --password goalie \
</opt/nuodb/samples/quickstart/sql/Players.sql >& /dev/null
nuosql test@nuoadmin1 --schema hockey --user dba --password goalie \
</opt/nuodb/samples/quickstart/sql/Scoring.sql >& /dev/null
nuosql test@nuoadmin1 --schema hockey --user dba --password goalie \
</opt/nuodb/samples/quickstart/sql/Teams.sql >& /dev/null

Run Sample SQL Statements

Invoke an interactive nuosql session using the name of the "test" database in the NuoDB Admin service container "nuoadmin1", with the user credentials we set above, and try out some simple nuosql commands:

nuosql test@nuoadmin1 --user dba --password goalie
USE hockey;
SHOW tables;
Tables in schema HOCKEY
        HOCKEY
        PLAYERS
        SCORING
        TEAMS
        VW_PLAYER_STATS is a view

In the above example, USE hockey switches context to the "HOCKEY" schema from the default "USER" schema and SHOW tables shows the tables in that schema.

Try out some more nuosql commands on the hockey database, such as:

SELECT * FROM teams WHERE teams.year=2011;

Now try a more advanced query such as:

SELECT p.lastName, p.firstName, s.year, s.teamID, s.gamesPlayed
FROM   players p, scoring s
WHERE  p.birthCountry='Slovakia'
AND    s.playerID = p.playerID order by p.lastName;

Try out some more NuoDB SQL commands as described in SQL Language, such as the SQL System Information Functions.

When you are finished, type quit to exit the interactive nuosql session.

Type exit to exit the bash shell in the "nuoadmin1" container.

Shutdown

To shut down the database and remove the SM and TE, run the following commands:

docker exec -it nuoadmin1 nuocmd shutdown database --db-name test
docker rm -f test-sm-1 test-te-1

The following command will show the nuoadmin process is still running and the state of the "test" database is NOT RUNNING:

docker exec -it nuoadmin1 nuocmd show domain

Restart

The SM and TE containers were removed in the Shutdown section above, so to restart, simply recreate them using the same commands used to start them initially above.

The volume "test-arch-vol-1" wasn’t removed, so when the SM is restarted, the existing database is still available.

Note that even if an SM exits for whatever reason, the data still persists, as long as it’s stored on persistent storage.
In the NuoDB Limited Use License, just one SM is permitted, but in a production deployment using the NuoDB Enterprise License, there would typically be several NuoDB Admin service instances and several SMs and TEs spread over two or more data centres or even cloud providers, with each SM having its own synchronised copy of the database archive, providing maximum resiliency. This is the beauty of the truly distributed NuoDB database architecture.

To see that the data persists, once you’ve recreated the SM and TM containers, re-invoke the bash shell in "nuoadmin1" and start an interactive nuosql session as done previously, but without re-importing the ice hockey sample database.

When finished, quit out of the nuosql session and exit out of the bash shell in "nuoadmin 1".

Clean Up

To clean up and remove all resources, simply delete the NuoDB containers, storage volumes, and network:

docker rm -f nuoadmin1 test-sm-1 test-te-1
docker volume rm -f nuoadmin-raft-1 test-arch-vol-1
docker network rm nuodb-net

Next Steps