Docker Compose install

Docker compose is a popular way to define multi-container applications using a infrastructure as code approach.

If you personally prefer to use docker compose, then here is a sample to get you started;

docker-compose.yml
services:
  olivetin:
    container_name: olivetin
    image: jamesread/olivetin
    volumes:
      - OliveTin-config:/config # replace host path or volume as needed
    ports:
      - "1337:1337"
    restart: unless-stopped


volumes:
  OliveTin-config:
    external: false

Post installation (container)

You will need to write a basic configuration file before OliveTin will startup.

Create a basic config file at /etc/OliveTin/config.yaml - the exact path depends on what directory you specified in the bind mount container creation in the last step. Note that the file must be called config.yaml, and config.yml or mystuff.yaml would not work. You can download a sample configuration file like this if you like;

Download the sample config.yaml file to get you started.
user@host: cd /etc/OliveTin/
user@host: curl -O https://raw.githubusercontent.com/OliveTin/OliveTin/main/config.yaml

The file contents should look something like this;

The most simple config.yaml file.
actions:
  - title: "Hello world!"
    shell: echo 'Hello World!'

If you are running a firewall on your server, like firewalld, you will need to open port 1337;

Configure your firewall

  • No Firewall

  • FirewallD

If you don’t have a firewall, continue to the next section.

This is how you configure your firewalld firewall for OliveTin:

user@host: firewall-cmd --add-port 1337/tcp --permanent
user@host: firewall-cmd --reload

Start the OliveTin service

Now that you have a configuration file, and the OliveTin container created, you are now ready to start OliveTin!

user@host: docker start olivetin

You should be able to browse to http://yourserver:1337 (or similar) to get to the web interface.

If you see the OliveTin page popup in your browser, you are good to go! Here are some helpful next steps;

Troubleshooting podman/docker installations

If you are having problems in starting OliveTin, or OliveTin is crashing on startup, then check the logs like this;

user@host: docker logs OliveTin

For more detail on what to capture and how to share logs when asking for help, see Service logs (troubleshooting).

If you cannot understand the logs, or otherwise need help, see the support page.

Controlling other docker containers from a Docker Compose install of OliveTin

If you want OliveTin running in a container to control other Docker containers, pass the Docker socket into the service and give the container process membership in the same numeric docker group that owns the socket on the host.

On many Linux installs, Docker Engine creates a docker group automatically; see Manage Docker as a non-root user in the Docker documentation.

Find the docker group GID on the host

On the Docker host, read the docker group numeric ID (third field of the output):

getent group docker

If that command prints nothing, create the group or finish Docker post-install steps first, then retry.

Add the socket mount and group_add in Compose

In docker-compose.yml, bind-mount the socket and add group_add with that GID (as a string is fine). Replace the example GID with the value from your host:

docker-compose.yml including Docker socket access without running as root
services:
  olivetin:
    container_name: olivetin
    image: jamesread/olivetin
    volumes:
      - /docker/OliveTin:/config # replace host path or volume as needed
      - /var/run/docker.sock:/var/run/docker.sock
    group_add:
      - "992" (1)
1 Replace 992 with the GID from getent group docker on the machine where Compose runs. The number is not portable between hosts.

This keeps the default container user while allowing access to /var/run/docker.sock, which is usually tighter than running the whole service as root.

See containers for docker run, --privileged, and other options if you cannot use a docker group on the host.

Running the OliveTin container as a different user in Compose

If you need the service to run as a specific Unix user in Compose for reasons other than Docker socket access, set user explicitly, for example:

services:
  olivetin:
    container_name: olivetin
    image: jamesread/olivetin
    user: "1000:1000"
    ...

For Docker socket access from Compose, prefer group_add with the host docker group GID instead of user: root.

PUID and PGID are not used by the official OliveTin container image.

Using Traefik with Docker Compose

Traefik is a popular reverse proxy that seems to be used a lot in people’s Docker compose setups. See the Traefik + Docker Compose page for more details.