Docker or Podman
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 [install-container-vs-service] 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.
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;
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;
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;
-
configuration section for a list of all configuration options.
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.