Outdated!

We moved the docker-compose file to the (now mono)repo ccs-amsterdam/amcat4. Please see the instructions there to download the new docker-compose file, which will pull new images for the frontend and backend.

Docker compose file and docker containers for AmCAT4

This repository contains a docker-compose.yml file for running AmCAT4. It is setup to allow both local development/testing use as well as production setup.

Usage

Step 0: Install docker and docker-compose

See the official docker documentation and/or their specific instructions for linux.

Step 1: Clone the repository

git clone https://github.com/ccs-amsterdam/amcat4docker
cd amcat4docker

Step 2: Launch the docker

docker compose up -d

Note: You might need to use sudo docker and/or docker-compose instead of docker compose depending on your installation.

In the default configuration, the web interface should now be available at http://localhost. On a server, you can test with:

curl localhost/amcat

Note that it might take about a minute to boot everything up, so if you don't see anything wait a second and refresh.

Configuring AmCAT

The configuration of AmCAT4 is controlled through a .env file, for which an example is given in this repository.

Especially for production use (i.e. on a server accessible to your lab or the world), be sure to edit at least the hostname, cookie secret, authentication, and data storage.

To edit the configuration, copy .env.example to .env and edit it:

cp .env.example .env
nano .env

After editing, either restart individual containers or just run

docker compose down
docker compose up -d

Updating

If a new build is released, you can update the compose file and pull in the new docker images:

docker compose down
git pull
docker compose pull
docker compose up -d

It might be good to check the .env.example file to see if any changes have been made that would affect your configuration.

Troubleshooting

If something isn't work, check whether all containers are running with

docker ps

To see the logs for a specific container, e.g. amcat4, run:

docker logs -f amcat4

Container overview

AmCAT consists of four main services:

• amcat4client is the main web UI, based on ccs-amsterdam/amcat4client
• amcat4 is the backend/API, based on ccs-amsterdam/amcat4
• an elasticsearch database is used to store and index the documents
• a 'caddy' web server exposes the client and api so they can be reached on localhost (default) or using an external domain name.

For more information about AmCAT, see the amcat manual.

Building your own images

To build the images you need to include the docker-compose.build.yml, either on the command line:

docker compose -f docker-compose.yml -f docker-compose.build.yml build --no-cache

Or by adding the compose file to your .env file:

COMPOSE_FILE=docker-compose.yml:docker-compose.dev.yml

Note that the changes won't be reflected until you restart the images using docker compose down && docker compose up -d

Upload to dockerhub (for Contributors)

If you've made changes to amcat4 or amcat4client and wish to update the images on docker hub, run docker login and then:

docker image push --all-tags ccsamsterdam/amcat4 && \
  docker image push --all-tags ccsamsterdam/amcat4client