Offen¶
Offen is an open alternative to common web analytics tools. Gain insights while your users have full access to their data. Lightweight, self hosted and free.
License¶
Offen is distributed under the Apache 2.0 license which can be found here:
For information about third party software bundled by Offen, check the NOTICE file included in the download.
Prerequisites¶
Your Offen subdomain needs to be setup (note that this does not need to contain the word “offen”, it can also be “analytics” or whatever you feel like):
[isabell@stardust ~]$ uberspace web domain list
isabell.uber.space
offen.yourdomain.org
[isabell@stardust ~]$
Note
This subdomain setup is required so that Offen can set cookies from the same domain that your target site is running on. I.e. if your site is running on www.yourdomain.org, Offen is ideally running on offen.yourdomain.org. You could use the isabell.uber.space domain if you want to, but that will make Offen issue 3rd party cookies, which are subject to blocking in many scenarios. A domain can be added at a later point in time though.
You’ll need your MySQL credentials. Get them with my_print_defaults:
[isabell@stardust ~]$ my_print_defaults client
--default-character-set=utf8mb4
--user=isabell
--password=MySuperSecretPassword
[isabell@stardust ~]$
Installation¶
Download the binary distribution¶
Offen is distributed as a single binary file. To kick off your install, download the latest release:
[isabell@stardust ~]$ mkdir -p ~/tmp/offen-download
[isabell@stardust ~]$ curl -sSL https://get.offen.dev | tar -xvz -C ~/tmp/offen-download
LICENSE
NOTICE
README.md
checksums.txt
offen-darwin-10.6-amd64
offen-darwin-10.6-amd64.asc
offen-linux-amd64
offen-linux-amd64.asc
offen-windows-4.0-amd64.exe
offen-windows-4.0-amd64.exe.asc
[isabell@stardust ~]$
Note
The distribution tarball also contains non-Linux binaries which is why you also see those darwin and windows files. We will delete them later.
Next, we should check if the binary matches the signature - i.e. it has not been altered by 3rd parties - using GPG (this step is optional, but highly recommended):
[isabell@stardust ~]$ curl -sSL https://keybase.io/hioffen/pgp_keys.asc | gpg --import
gpg: key C90B8DA1: public key "Offen (Signing Binaries) <hioffen@posteo.de>" imported
gpg: Total number processed: 1
gpg: imported: 1 (RSA: 1)
gpg: no ultimately trusted keys found
[isabell@stardust ~]$ gpg --verify ~/tmp/offen-download/offen-linux-amd64.asc ~/tmp/offen-download/offen-linux-amd64
gpg: Signature made Mo 13 Jul 2020 18:05:28 CEST using RSA key ID C90B8DA1
gpg: Good signature from "Offen (Signing Binaries) <hioffen@posteo.de>"
gpg: WARNING: This key is not certified with a trusted signature!
gpg: There is no indication that the signature belongs to the owner.
Primary key fingerprint: F20D 4074 068C 636D 58B5 3F46 FD60 FBED C90B 8DA1
[isabell@stardust ~]$
Note
GPG will print warnings about the signing key not being certified as your Uberspace’s keyring is likely empty and does therefore not know about anyone who has signed Offen’s key. This is expected behavior. You can check the Offen Keybase profile for further proof that this key is the correct one.
Install the command¶
Next, you can install the Linux binary on your Uberspace:
[isabell@stardust ~]$ cp ~/tmp/offen-download/offen-linux-amd64 ~/bin/offen
[isabell@stardust ~]$ which offen
~/bin/offen
[isabell@stardust ~]$
Cleaning up¶
You can now safely delete the downloaded files (remember to check or keep LICENSE and NOTICE files if you are interested in such things):
[isabell@stardust ~]$ rm -rf ~/tmp/offen-download
[isabell@stardust ~]$
Configuration¶
Create a config file¶
In its most basic setup, Offen sources configuration values from an
offen.env file, that is expected in ~/.config/offen.env:
[isabell@stardust ~]$ mkdir -p ~/.config
[isabell@stardust ~]$ touch ~/.config/offen.env
[isabell@stardust ~]$
Populate the config file¶
For Offen to run on your Uberspace you will need to populate this .env
file with the following:
A Secret¶
Offen requires a unique secret for signing login cookies and certain URLs. You
can use the offen command you just installed to create one for you
(passing -quiet will make secret output the generated value
only):
[isabell@stardust ~]$ echo "OFFEN_SECRET=$(offen secret -quiet)" >> ~/.config/offen.env
[isabell@stardust ~]$
Note
Changing this secret at a later point is possible, but will invalidate all currently active login sessions, as well as all pending invites or password resets.
Database setup¶
Offen will store its data in the MariaDB provided by your Uberspace. First, create a dedicated database for Offen to use:
[isabell@stardust ~]$ mysql -e "CREATE DATABASE ${USER}_offen"
[isabell@stardust ~]$
Next, edit the config file at ~/.config/offen.env and append the dialect
and the connection string (do not overwrite the secret you just created):
OFFEN_DATABASE_DIALECT=mysql
OFFEN_DATABASE_CONNECTIONSTRING="isabell:MySuperSecretPassword@tcp(localhost:3306)/isabell_offen?parseTime=true"
SMTP credentials¶
Offen needs to be able to send out transactional email so that you can:
reset your password in case you forgot it
invite others to collaborate with you on this instance
Note
This section uses your Uberspace’s default mail setup because it’s easy and already present, but you are free to use whatever SMTP service you like if you have different requirements.
Edit ~/.config/offen.env and append the SMTP credentials like this (do not
overwrite the existing values):
OFFEN_SMTP_HOST="stardust.uberspace.de"
OFFEN_SMTP_PASSWORD="YourSuperSecretPassword"
OFFEN_SMTP_USER="isabell@uber.space"
OFFEN_SMTP_SENDER="isabell@uber.space"
Note
For your @uber.space address the password is the same as for SSH
access, which you can set in your dashboard.
Setup the daemon¶
Offen needs to run at all times so it can accept incoming events. Create a file
~/etc/services.d/offen.ini and populate it with the following:
[program:offen]
command=%(ENV_HOME)s/bin/offen
autostart=yes
autorestart=yes
After creating the configuration, tell supervisord to refresh its configuration and start the service:
[isabell@stardust ~]$ supervisorctl reread
SERVICE: available
[isabell@stardust ~]$ supervisorctl update
SERVICE: added process group
[isabell@stardust ~]$ supervisorctl status
SERVICE RUNNING pid 26020, uptime 0:03:14
[isabell@stardust ~]$
If it’s not in state RUNNING, check the logs and your configuration.
Point the web backend to Offen¶
As a last step you need to point your web backend to your Offen service.
Note
Offen is running on port 3000.
To make the application accessible from the outside, configure a web backend:
[isabell@stardust ~]$ uberspace web backend set / --http --port <port>
Set backend for / to port <port>; please make sure something is listening!
You can always check the status of your backend using "uberspace web backend list".
[isabell@stardust ~]$
Note
If you need to use a different port, set OFFEN_SERVER_PORT in your
configuration file.
Note
Uberspace set X-Frame-Options: SAMEORIGIN by default. You need to suppress it, if you run into problems: uberspace web header suppress / X-Frame-Options.
Finishing the installation¶
Point your browser to the https://offen.yourdomain.org/setup/ page and create your user and a first account.
Embedding Offen on your website¶
All you need to do to embed your Offen install on a website is to add the script to your document:
<script async src="https://offen.yourdomain.org/script.js" data-account-id="<YOUR_ACCOUNT_ID>"></script>
Note
You will also find this snippet for copy / pasting when you log in to your account.
Updating the version in use¶
If you want to update Offen to a newer version than you have originally installed, repeat the steps in the Download section.
After having done so, stop the daemon, update the binary, check its version and restart the daemon:
[isabell@stardust ~]$ supervisorctl stop offen
[isabell@stardust ~]$ cp ~/tmp/offen-download/offen-linux-amd64 ~/bin/offen
[isabell@stardust ~]$ offen version
INFO[0000] Binary built using revision=v0.1.1
[isabell@stardust ~]$ rm -rf ~/tmp/offen-download
[isabell@stardust ~]$ supervisorctl start offen
[isabell@stardust ~]$
Note
Before upgrading, always check the Releases page to confirm your
update is compatible with the version you are running. Running
offen version will tell you which version your Uberspace is currently
using.
Refer to the documentation for info on how to download a specific version of Offen.
Official docs¶
Offen has a dedicated documentation site that will tell you more about how to use and configure Offen.