Installation Guide

There are many ways to install OliveTin which are listed below.

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.

Containers vs Services

Linux Containers have become an incredibly popular method for running software. OliveTin supports every way of running Linux containers - spanning from homelabs up to enterprise environments. As a container, it can be used standalone using Podman/Docker, through to using docker-compose or even on Kubernetes.

However, a lot of OliveTin use cases, such as providing an interface to run scripts, rely on files on their local Linux filesystem - containers, by definition, have their own separate filesystem. It is of course possible to "bind mount" parts of your local filesystem into OliveTin, but sometimes this requires more effort, or introduces subtle problems that are more complicated to solve. If you have a good amount of experience with Linux containers, then this approach is absolutely fine - but if you are new to these types of problems - not seeing files you expect, file permissions errors, etc, then it might just be easier to install using a Linux package instead.

Don’t overcomplicate your containers - use SSH!

Sometimes you just want to (or have to) use containers, but also want to use these local resources as well. Instead of bind-mounting lots of stuff into the Linux container and creating a really complicated container definition (which is hard to scale), consider a simple alternative: SSH with OliveTin. This allows you to easily SSH back into the container host and keep your container definition really simple. This approach works great and is popular for a lot of users.

Which should I choose?

Use Case Recommended Option

You’re experienced with Linux containers, and know how to bind mount volumes

Linux Container

You’re new to Linux containers, or not very comfortable with them

Linux service, or Linux container with SSH action

Needs to use lots of different file paths on the host filesystem

Run as a systemd service, or bind-mount the filesystem into the container.

Needs to control processes, like systemd services

Run as a systemd service.

Which download do I need?

OliveTin can be run as a service or a container. If you are not sure which is best for you, read containers vs services.

Packages (run OliveTin as a service)

This is a table that explains which package/download is best for each environment;

Processor Type Operating System Distribution File on latest release page

AMD / Intel → amd64

Linux

Other → .tar.gz

OliveTin-linux-amd64.tar.gz installation instructions

Red Hat, Fedora, etc → .rpm

OliveTin_linux_amd64.rpm installation instructions

Debian, Ubuntu → .deb

OliveTin_linux_amd64.deb installation instructions

Windows

OliveTin-windows-amd64.zip

macOS,macOS

OliveTin-macOS-amd64.tar.gz

32bit ARM (Raspberry Pi 1, 2, or similar) → arm

Linux

Other → .tar.gz

One of the OliveTin-linux-arm…​.tar.gz files installation instructions

Red Hat, Fedora, etc → .rpm

One of the OliveTin_linux_arm…​..rpm files installation instructions

Debian, Ubuntu → .deb

One of the OliveTin_linux_arm…​.deb files installation instructions

64bit ARM (Apple M1, Raspberry Pi 3, 4, or similar) → arm64

Note: If you are running 32bit Raspberry Pi OS, choose the 32bit ARM download option instead.

Linux

Other → .tar.gz

OliveTin-linux-arm64.tar.gz installation instructions

Red Hat, Fedora, etc → .rpm

OliveTin_linux_arm64.rpm installation instructions

Debian, Ubuntu → .deb `

OliveTin_linux_arm64.deb installation instructions

macOS

OliveTin-macOS-arm64.tar.gz installation instructions

A full list of packages can be downloaded from the GitHub project releases page.

Container images

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;

The following methods can be used to install the container;

Linux package install (.rpm/.deb)

Running OliveTin as a systemd service on a Linux machine means it can use any program installed on your machine (you don’t have to add programs to a container). This is generally easier to use than a container, but containers can work just fine too with a bit more effort.

Choosing the right Linux package

There are .deb, .rpm, and similar packages published for OliveTin on each release page. Pick a package most relevant to the Linux distribution you are using from the downloads page.

If you’re not sure which package to use, see which download do I need?

You can install these packages with your Linux package manager (eg, dpkg -i OliveTin…​deb or rpm -U OliveTin…​rpm).

Post installation

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

Create the following basic config file at /etc/OliveTin/config.yaml with the following contents;

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

Now that you have a configuration file, and OliveTin is installed, start it;

Start the service (only needed once)
user@host: systemctl enable --now OliveTin

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

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 systemd installations

If you are having problems, you can check if OliveTin is running like this;

user@host: systemctl status OliveTin

If the service has failed, scroll through the logs;

user@host: journalctl -eu OliveTin

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

Fedora Linux (dnf)

Fedora is included in the Fedora Project official repositories. For an overview of versions, see the Package Sources page;

https://src.fedoraproject.org/rpms/OliveTin

Installation

Install using dnf (or yum, on older versions of Fedora);

user@host: dnf install -y OliveTin

Post installation

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

Create the following basic config file at /etc/OliveTin/config.yaml with the following contents;

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

Now that you have a configuration file, and OliveTin is installed, start it;

Start the service (only needed once)
user@host: systemctl enable --now OliveTin

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

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 systemd installations

If you are having problems, you can check if OliveTin is running like this;

user@host: systemctl status OliveTin

If the service has failed, scroll through the logs;

user@host: journalctl -eu OliveTin

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

Alpine Linux

Alpine Linux is supported by an upstream .apk package, or a manual .tar.gz install, or by a container.

These instructions on this page are quite basic, because not many people have tried to use OliveTin on Alpine, or other OpenRC distributions. If you can help suggest improvements to these docs, or Alpine Linux support, it would be great to hear from you!

Installing the upstream .apk

user@host: wget https://github.com/OliveTin/OliveTin/releases/latest/download/OliveTin_linux_amd64.apk
user@host: apk add --allow-untrusted OliveTin_linux_amd64.apk

Installing the .tar.gz

The standard .tar.gz instructions should work just fine, replacing systemd for the OpenRC file.

Arch Linux (AUR)

There are 3 packages available for Arch Linux;

  1. olivetin in AUR - This builds from source, using a release Git tag.This is officially maintained by the authors of the OliveTin project.

  2. olivetin-bin in AUR - This re-packages the binaries built by the official binaries. This is not officially maintained by the authors of the OliveTin project, and might be a bit older - but it should work just fine.

  3. olivetin .apk built by the project - This may be useful to have a package outside of AUR.

Installation (AUR)

Install using yay;

user@host: yay -Syu olivetin

Post installation

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

Create the following basic config file at /etc/OliveTin/config.yaml with the following contents;

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

Now that you have a configuration file, and OliveTin is installed, start it;

Start the service (only needed once)
user@host: systemctl enable --now OliveTin

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

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 systemd installations

If you are having problems, you can check if OliveTin is running like this;

user@host: systemctl status OliveTin

If the service has failed, scroll through the logs;

user@host: journalctl -eu OliveTin

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

Manjaro (pamac/AUR)

Please see teh Arch Linux (AUR) page for a description of the difference between olivetin-bin and olivetin in AUR. This page assumes you want to compile from source (olivetin package).

PATH=$PATH:~/go/bin/
pamac install buf
pamac install olivetin
sudo mkdir -p /etc/OliveTin/custom-webui/themes/
sudo mkdir -p /etc/OliveTin/entities/

Post installation

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

Create the following basic config file at /etc/OliveTin/config.yaml with the following contents;

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

Now that you have a configuration file, and OliveTin is installed, start it;

Start the service (only needed once)
user@host: systemctl enable --now OliveTin

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

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 systemd installations

If you are having problems, you can check if OliveTin is running like this;

user@host: systemctl status OliveTin

If the service has failed, scroll through the logs;

user@host: journalctl -eu OliveTin

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

Container install (podman/docker)

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;

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
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.

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
version: "3.8"
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

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.

Controlling other docker containers from a Docker Compose install of OliveTin

If you want to use OliveTin running in a container to control other Docker containers, you will need to pass through the Docker sock in your compose file.

You will need to adjust your docker-compose file to include the docker socket, like this;

`docker-compose.yml` including docker socket
version: "3.8"
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
    ...

You will probably need to tell this container to run as root as well, to control docker (see below).

Controlling the docker user with Docker Compose

This is the correct way to tell the OliveTin container to run as root (or any other user);

version: "3.8"
services:
  olivetin:
    container_name: olivetin
    image: jamesread/olivetin
    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.

Kubernetes with Helm

Helm makes installing OliveTin on Kubernetes very easy, the official chart is hosted on Artifact Hub.

Artifact Hub

Quickstart

user@host: helm repo add olivetin https://olivetin.github.io/OliveTin-HelmChart/
user@host: helm install olivetin olivetin/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.

Included templates

You can view the raw templates here: https://github.com/OliveTin/OliveTin-HelmChart/tree/main/templates

  • Deployment

  • ConfigMap

  • Service

  • Ingress (optional)

Kubernetes with Manifest files

OliveTin works just fine on Kubernetes. The easiest way to deploy it is with a Kubernetes ConfigMap, Deployment, Service and finally Ingress. Like so;

ConfigMap
kubectl apply -f http://docs.olivetin.app/etc/k8s_configmap.yml

The main application config.yml for OliveTin is specified in the ConfigMap above. You will want to edit this later - see the "Configuration" section.

Next, we need a deployment;

Deployment
kubectl apply -f http://docs.olivetin.app/etc/k8s_deployment.yml

That should deploy OliveTin. Then expose it as a service;

Service
user@host: kubectl expose deployment/olivetin

Then lastly, create a Ingress rule for for that service;

Ingress
kubectl apply -f http://docs.olivetin.app/etc/k8s_ingress.yml

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.

.tar.gz Install (manual)

This is an option for an advanced setup, for users who cannot user the .deb or .rpm packages.

Manual setup (.tar.gz)

A .tar.gz file is provided for people who are using other Linux distributions or want to set things up manually.

  1. Copy the OliveTin binary to /usr/local/bin/OliveTin

  2. Copy the webui directory contents to /var/www/olivetin/ (eg, /var/www/olivetin/index.html)

  3. Copy the OliveTin.service file to /etc/systemd/system/

  4. Create a config.yaml in /etc/OliveTin using the example provided above to get you started.

Post installation

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

Create the following basic config file at /etc/OliveTin/config.yaml with the following contents;

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

Now that you have a configuration file, and OliveTin is installed, start it;

Start the service (only needed once)
user@host: systemctl enable --now OliveTin

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

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 systemd installations

If you are having problems, you can check if OliveTin is running like this;

user@host: systemctl status OliveTin

If the service has failed, scroll through the logs;

user@host: journalctl -eu OliveTin

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