This repository has the basic configuration useful for starting and running Elements from the images available on Docker Hub
- Docker Version 24.0.2, or Greater
- Clone this repository.
- Navigate to the cloned directory in your terminal.
- Start services using
docker compose up
Warning
The tagging system is currently being worked on. If the above command does not work,
try using the alternative tag command with a specific version, e.g. TAG=3.0.18-SNAPSHOT docker compose up
For a list of available tags, see here: https://github.com/NamazuStudios/elements/tags
When Jenkins runs a branch build for Elements, it will make tags based on the abbreviated git commit format. The container image is determined based on the TAG environment variable. To evaluate a tag version of Elements, use these steps.
- Clone this repository.
- Navigate to the cloned directory in your terminal.
- Start services using
TAG=footag docker compose
For a list of available tags, see here: https://github.com/NamazuStudios/elements/tags
docker-compose tends to avoid fetching and recreating new containers
once already up and running. Fetching new containers for a specific tag,
sometimes it is necessary to delete local containers before doing the update.
This can be accomplished using the following docker compose.
docker compose stop && docker compose rm
This will stop and delete all local containers, but will leave the volumes. It
is a good idea to force a pull of the latest from the repository, as indicated
by docker compose rm --help
myuser@mybox:~/path/to/docker-distribution docker compose rm --help
Removes stopped service containers.
By default, anonymous volumes attached to containers will not be removed. You
can override this with `-v`. To list all volumes, use `docker volume ls`.
Any data which is not in a volume will be lost.
Usage: rm [options] [SERVICE...]
Options:
-f, --force Don't ask to confirm removal
-s, --stop Stop the containers, if required, before removing
-v Remove any anonymous volumes attached to containers
-a, --all Deprecated - no effect.
When starting services again, you can force a rebuild with the desired tag as
follows. Replace DesiredTag with the specific release you wish to run.
Mac/Linux:
TAG=DesiredTag docker compose build --pull && docker compose up
Windows:
For PS: set TAG=DesiredTag ; docker compose up --build
For CMD: set "TAG=DesiredTag" && docker compose up --build
Note
Multiple ways exist to get Docker to rebuild the containers. Various versions may handle this a slight bit differently.
Once up and running you will the following containers running using the following command
docker psThe output of which should show the following
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
Each running container serves the following purpose:
- ws runs the entire application in a single container. It is exposed on port 8080 on the local machine.
- app-node-x runs all background services which are responsible for executing cloud functions. Two separate containers are defined to simulate the effects of the node cluster when running in the cloud.
- rs-init runs dnsmasq to serve SRV records which enable all services to discover the nodes in the cluster.
- mongo a self-hosted version of MongoDB
When running the whole stack, the following ports are in-use and are exposed on the host machine.
- 8080 is the main entrypoint for the application.
- 28883 & 28884 run the app-node protocol. (This one isn't commonly accessed directly unless you're doing some advanced debugging)
- 27017 runs MongoDB. For debugging purposes, it is often useful to connect the mongo client here for the purposes of inspecting the database.
If no user exists in the database, one will be created by default with the SUPERUSER access level. It will have the following login credentials:
username: root
password: example
It is highly recommended that you log in (http://localhost:8080/admin/login while running Elements locally) with these credentials to this default account, and either change the password, or create a new SUPERUSER account and delete the default account.
If you're using Docker Desktop then you can use it to stop, reset, and re-launch the containers after you've run the docker compose up command once. Unfortunately, they do no provide a way to register a docker compose project without running it from the command line/terminal first.
Running docker compose up will automatically follow along all of the logs that Elements generates. If you run docker compose up -d however, it will run in "detached" mode, and it will not display logs for you in the terminal. If you then want to re-follow the logs later, you can use docker compose logs -f to show the logs and "follow" them.