Managing and Updating BLAM Docker Deployments
Once a BLAM has been deployed on an environment running as Docker Containers, it will largely manage itself and recover from any errors. But there may be cases where intervention is needed, such as to update the BLAM Containers or when making changes to storage configuration.
Configure AWS CLI
Ensure you have configured the AWS CLI for BLAM Container Access. The credentials will be provided to by Blue Lucy for access to their Elastic Container Repository and and S3 Bucket location used for installation files.
$ aws configure
AWS Access Key ID = [ACCESS_KEY_ID provided by Blue Lucy]
AWS Secret Access Key = [SECRET_ACCESS_KEY provided by Blue Lucy]
Default region name = eu-west-1
Default output format = None
Docker Login to AWS
To allow Docker to access the Container Images in our Elastic Container Repository, the Docker tool must be logged in using the AWS Credentials. This login will remain valid for 12 hours. It is best to re-run this Login command whenever making any changes to containers to ensure our Elastic Container Repository can be accessed.
$ aws ecr get-login-password --region eu-west-1 | sudo docker login --username AWS --password-stdin 365894649245.dkr.ecr.eu-west-1.amazonaws.com
Docker Compose Files
On each machine using Docker to run BLAM Containers will be a Docker Compose YML file (docker-compose.yml).
This should be located inside the /home/#user# directory, where #user# is the account used to connect and setup the BLAM (e.g. ec2-user for AWS EC2, azureuser for Microsoft Azure).
Execute all Docker commands from within the directory containing the Docker Compose file.
The Docker Compose file can be edited in place using any text editor (nano, vim) or downloaded, edited externally and re-uploaded.
We do not recommend you edit this file unless you know exactly what you are doing.
Editing this file incorrectly could break your BLAM and stop your system from working.
Docker Container Versions
One simple area you may wish to edit in your Docker Compose file is the Container Version. For example to upgrade to our latest Full Release version, issued at the beginning of each month.
Each Container within a Docker Compose file containers the URI to a Docker Container Image in our Elastic Container Repository, including which Version of this container will be used.
Depending on your business model, you may want to only run Full Release Builds, or you may want to update your system more frequently to get Hotfix Builds or the latest available build.
This sets the ‘api’ Container to use the ‘latest’ available container image found at the specified URI. If you wish to always use the Latest available BLAM software, using the tag ‘:latest’ ensures whenever you pull the containers the most recent builds will be used.
This comes with the risk that the latest code may contain new or developmental features still being tested.
Official Releases and Hotfix Releases
BLAM is released on a Monthly build cycle, with a new Full Release Version indicating the Year and Month of the release, e.g. 2106 for June 2021 (06/2021). Hotfix releases will be built as required, indicated by an incremental version on the Master Release.
The example here is set to a Hotfix Release Build (here, 2106.1, June 2021, Hotfix 1), so that when a pull is performed, it will always use this exact container version. This will allow you to run a single version of BLAM software, which has been fully tested and officially released.
Any Hotfixes made during one month will automatically be part of the following month’s Full Release Build – so it is not necessary to install the Hotfix Build unless you are directly affected by the issue it addresses.
From inside the directory containing your Docker Compose file, you can perform the following commands to manage the running Docker Containers.
To pull (download) all container images configured in the Docker Compose file:
$ docker-compose pull # Downloads the container images from the URIs set in docker-compose.yml
To start all containers configured in the Docker Compose file:
$ docker-compose up
To start all containers silently (as a daemon, no output to the console):
$ docker-compose up -d
To stop all running containers configured in the Docker Compose file:
$ docker-compose down
To restart all running containers configured in the Docker Compose file:
$ docker-compose restart
Note that a Restart will restart the Container versions which are already running. It will not change the version. If the available Container Image has changed (e.g. when using :latest) or you want to update to the a different Release Version, you will need to follow the steps below.
Updating the BLAM
To Update the BLAM, or any of it’s component containers, you will need to download the new container images from out Elastic Container Repository and may also need to apply Migration Changes to the BLAM Databases.
When a new BLAM version is released, new Docker Containers are built and published to our Elastic Container Repository. If you are configured to use the ‘:latest’ containers in your Docker Compose file, or have updated these to use the latest Release version, you need to perform a Pull to get these updated containers from the Elastic Container Repository.
$ docker-compose pull # Downloads the latest containers (will not change what is running until you complete the next steps)
$ docker-compose down # Stops all running containers
$ docker-compose up -d # Starts all containers using the last 'pulled' version
View Running Containers
To view a breakdown of all running containers, including current up-time values, use the PS command.
$ docker ps
Updating BLAM Database
When a BLAM Release Build is made, this may require changes (called migrations) to be applied to the existing BLAM Databases. Without doing so you are likely to experience errors in the system as the running software may not match the database structure.
A BLAM Database Migration tool is built and published into our S3 Bucket to streamline this process. Download and run this tool for the correct BLAM Release Version you want to run e.g. v3.2106.
$ aws s3api get-object --bucket bl-installation-media --key BLAM3DbMigrationTool-linux-x64-v3-2106.zip ./BLAM3DbMigrationTool-linux-x64-v3-2106.zip
$ unzip BLAM3DbMigrationTool-linux-x64-v3-2106.zip -d ./blam-db-tool/
$ ./blam-db-tool/BLAM3DbMigrationTool # Run the DB Migration Tool and follow the steps for Applying the Database Migrations
Enter 0 – Update Database
Enter 1 – Postgres Database type
Connection string: Host=localhost;Database=BLAM3;Username=postgres;Password=[#YOUR_DATABASE_PASSWORD as set in docker-compose.yml#]
After the BLAM Database Migration Tool completes, you should then restart your Database Container (or do a full restart of all containers).
$ sudo docker-compose up -d --no-deps --build --force-recreate db-postgres # Restart the Database container only