This tutorial walks you through the steps needed to setup and deploy a standalone, single-node Offen instance that is using a local SQLite file as its database backend.
- Storing your data
- Running the
- Setting up AutoTLS
- Setting up email
- Verifying your config file
- Starting the application
In the simple setup described in this tutorial Offen needs to read and persist the following data:
- a database file
- cache files for the SSL certificates
- a configuration file
Keeping these files available at any time is required for running the application, so make sure they are not stored on ephemeral systems. If you plan to deploy to a ephemeral host (e.g. Heroku), check “Configuring The Application At Runtime” for how to configure the application using environment variables and connecting to a remote Database.
First we need to create two Docker volumes for persisiting the SQLite database and SSL certificates:
docker volume create offen_data docker volume create offen_certs
Next, we create an empty file for holding the runtime configuration:
mkdir -p ~/.config touch ~/.config/offen.env
The config file in
~/.config/offen.env assumes you are on Linux and want to follow an established pattern for storing configuration files. In the end, any other location will work too, so feel free to change this depending on your setup and needs.
Offen lets you setup a new instance using the
The value provided to the
name is the name of the first account to be created. The password for your login will be requested in a prompt. Passing
-populate will create required secrets in the
docker run -it --rm \ -v offen_data:/var/opt/offen \ -v offen_certs:/var/www/.cache \ --mount type=bind,src=/home/you/.config/offen.env,dst=/etc/offen/offen.env \ offen/offen:v0.1.0-alpha.7 setup \ -email email@example.com \ -name mysite \ -populate
When finished, the command has created an account for you, using the given name and credentials.
offen.env file will now look something like this:
OFFEN_SECRET="uNrZP7r5fY3sfS35tbzR9w==" # do not use this secret in production
The official Docker image is available as
offen/offen on Docker Hub. The most recent official release is tagged as
v0.1.0-alpha.7 (which is also what the above command is using). If you are feeling adventurous, or require features that are not yet available in a release you can also use the
latest tag which represents the latest state of development. Be aware though that these versions might be unstable.
Offen requires a secure connection and can automatically acquire a renew SSL certificates from LetsEncrypt for your domain. All you need to do is add the domain you want to serve Offen from to your
To make sure the automatic certificate creation and renewal works, make sure your host system exposes both port 80 and 443 to the public internet.
Offen needs to send transactional email for the following features:
- Inviting a new user to an account
- Resetting your password in case you forgot it
To enable this, you can add SMTP credentials, namely Host, User, Password and Port to the
OFFEN_SMTP_HOST="smtp.mysite.com" OFFEN_SMTP_USER="me" OFFEN_SMTP_PASSWORD="my-password" OFFEN_SMTP_PORT="587"
Offen will run without these values being set and try to fall back to a local
sendmail install, yet please be aware that if you rely on any of the above features email delivery will be unreliable if not configured correctly. You can always add this at a later time though.
Before you start the application, it’s a good idea to double check the setup. Your config file should now contain an entry for each of these values:
OFFEN_SECRET="uNrZP7r5fY3sfS35tbzR9w==" # do not use this secret in production OFFEN_SERVER_AUTOTLS="offen.mysite.com" OFFEN_SMTP_HOST="smtp.mysite.com" OFFEN_SMTP_USER="me" OFFEN_SMTP_PASSWORD="my-password" OFFEN_SMTP_PORT="587"
If all of this is populated with the values you expect, you’re ready to use Offen.
To start Offen use the Docker image’s default command:
docker run -d \ -p 80:80 -p 443:443 \ --name offen \ -v offen_data:/var/opt/offen \ -v offen_certs:/var/www/.cache \ --mount type=bind,src=/home/you/.config/offen.env,dst=/etc/offen/offen.env \ offen/offen:v0.1.0-alpha.7
Once the application has started, you can use
docker ps to check if it’s up and running:
$ docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 70653aca75b4 offen/offen:v0.1.0-alpha.7 "offen" 5 minutes ago Up 5 minutes 80/tcp, 443/tcp offen
Your instance is now ready to use. Once you have setup DNS to point at your host system, you can head to
https://offen.mysite.com/login and login to your account.
To stop the running container, run
docker stop offen
To read log output, use
docker logs offen