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.
systemd is used for managing the Offen service.
Note If you get stuck or need help, file an issue, tweet (@hioffen) or email. If you have installed Offen and would like to spread the word, we’re happy to feature you in our README. Send a PR adding your site or app and we’ll merge it.
- Downloading and installing the package
- Configuring Offen
- Starting the
- Setting up the instance
This tutorial assumes the machine you are planning to run Offen on is connected to the internet and has DNS records for
offen.mysite.com (or the domain you are actually planning to use) pointing to it. Ports 80 and 443 are expected to be accessible to the public. See the documentation for subdomains for further information on this topic.
Offen version v0.1.6 and later is packaged as a Debian package, so installation on Ubuntu (and other Debian based distributions) is easy. First, download the package for the latest release:
curl -sSL https://get.offen.dev/deb -o offen.deb
Next, you can verify the package’s signature using
dpkg-sig (this step is optional, but recommended):
curl https://keybase.io/hioffen/pgp_keys.asc | gpg --import dpkg-sig --verify offen.deb
The package itself can be installed using
sudo dpkg -i offen.deb
You can confirm that your installation is working as expected like this:
$ which offen /usr/local/bin/offen $ offen version INFO Current build created using revision=v0.2.3
You can now safely remove the download:
In this setup, Offen stores its runtime configuration in
/etc/offen/offen.env. This file has already been created on installation, so you can now populate it with the values required for your install.
Offen is using a secret to sign login cookies and tokens for resetting passwords or inviting users. You can generate a unique secret for your installation using the
offen secret subcommand:
$ offen secret INFO Created 16 bytes secret secret="S2dR9JYYTNG3+5QN+jxiwA=="
OFFEN_SECRET key with the value you just generated:
OFFEN_SECRET="S2dR9JYYTNG3+5QN+jxiwA==" # do not use this secret in production
If you do not set this config value, Offen will generate a random one every time it starts up. This means it works securely, yet all login sessions, password reset emails or invitations will be invalidated when the service restarts.
Offen requires a secure connection and can automatically acquire a renew SSL certificates from LetsEncrypt for your domain. Add the domain you want to use to serve Offen to
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, Sender, User, Password and Port to the
OFFEN_SMTP_HOST="smtp.mysite.com" OFFEN_SMTP_SENDER="email@example.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 very 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 at
/etc/offen/offen.env 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.
systemd is used to make sure Offen is up and running at all times (e.g. after rebooting or crashing) and accepts events. The
deb package has already creating a
systemd service for you on installation, so all you need to do now is start it:
sudo systemctl enable offen sudo systemctl start offen
You can check whether this worked correctly using
$ sudo systemctl status offen ● offen.service - Offen Service Loaded: loaded (/etc/systemd/system/offen.service; enabled; vendor preset: enabled) Active: active (running) since Mon 2020-01-27 15:57:58 CET; 1min ago Main PID: 6701 (offen) Tasks: 11 (limit: 4915) CGroup: /system.slice/offen.service └─6701 /usr/local/bin/offen
Your instance is now ready to use.
Now that Offen is up and running, you can create your login user and a first account by navigating to
https://offen.mysite.com/setup. You can create one user and one account here, but you can always add more later on.
After submitting the form, your Offen instance is ready to use.
The easiest way for accessing application logs in this setup is using
$ sudo journalctl -u offen offen: time="2020-01-27T15:57:41+01:00" level=info msg="Successfully applied database migrations" offen: time="2020-01-27T15:57:41+01:00" level=info msg="Server now listening on port 80 and 443 using AutoTLS" offen: time="2020-01-27T15:57:41+01:00" level=info msg="Cron successfully pruned expired events" removed=0
If you want to uninstall the service from your system, stop and disable the
sudo systemctl stop offen sudo systemctl disable offen
To update to a new version of Offen, download the package for the newer version and install:
curl https://get.offen.dev/deb -o offen.deb dpkg-sig --verify offen.deb sudo dpkg -i offen.deb
Confirm that this worked by having
offen print its updated version:
$ offen version INFO Current build created using revision=v0.2.12
You can now restart your service to pick up the changes:
sudo systemctl restart offen