OliveTin documentation

Container install (podman/docker)

Note

OliveTin is supported when run as a Linux Container in many different ways, and lot of OliveTin users will assume that a Linux Container is the best way to install OliveTin because Linux Containers are really popular…

However, it is very common that some OliveTin use cases become overcomplicated when a container is used, compared to running as a native service. Read the Containers vs Services document to understand if a container or a service is right for your use case.

The image is pushed to the following registries, pick the one that you prefer - the container images are identical so you only need one;

Dockerhub container image: docker.io/jamesread/olivetin
GitHub container image: ghcr.io/jamesread/olivetin

If you prefer to use docker-compose, then follow the docker-compose installation instructions.

The standard container setup just needs port 1337 forwarded for web traffic, and a volume to store the configuration file. Note that OliveTin containers expect the config to be in /config/ inside the container, but it doesn’t really matter where this directory is mounted from on the host. This documention uses the convention of /etc/OliveTin on the host, but /dockerStuff/OliveTin/ or similar would be fine.

Create the container (but don’t start it yet)

user@host: mkdir /etc/OliveTin/
user@host: # ie: Your config file is /etc/OliveTin/config.yaml on the host machine. We'll create this in the post-installation step.
user@host: docker pull jamesread/olivetin
user@host: docker create --name olivetin -p 1337:1337 -v /etc/OliveTin/:/config:ro docker.io/jamesread/olivetin

Note

The OliveTin container is built using fedora-minimal, which doesn’t use customizations that some people may be familiar with from popular projects like LSIO, or debian-based containers. The two top misunderstandings are PUID and PGID are ignored. Please see the instructions below if you’re not familiar with changing users or timezones.

Container user

OliveTin does not need to be run as a root, and does not need any special capabilities. If you want to change the user that OliveTin runs as, use --user when creating the container. OliveTin ignores PUID and PGID.

Container timezone

To change the changing the timezone requires a bound-mount from the host. Olivetin ignores the TZ variable as it is non-standard.

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;

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

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 can jump to the configuration section as the next step.

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

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