Requirements for installing Offen

In case you want to use Offen for collecting usage data in a production setup or similar, there are a few requirements to consider.


Table of contents

  1. Running the application as a service
  2. Usage of a subdomain
  3. https protocol
  4. Choosing a datastore
  5. Additional considerations
    1. Running the application behind a reverse proxy
    2. Transactional email

Running the application as a service

Offen as an application is a web server that binds to one or multiple TCP ports and listens for incoming traffic. This means that in a production setup you will need to ensure the process is always running and restarts on failure or system restart.

Choice of tools for this task depends heavily on your host OS. Alternatively, you can use the official Docker image that wraps the binary to have a unified interface across operating systems.

Usage of a subdomain

Offen uses the Same-origin policy for protecting usage data from being accessed by third party scripts.

In an example scenario where you are using your Offen instance to collect usage data for the domain www.mywebsite.org, your Offen instance should be bound to a different subdomain of the same host domain, e.g. offen.mywebsite.org. This ensures that

  1. usage data is accessible for that domain only
  2. third-party cookie restrictions do not apply

In the above scenario you would use Offen on your website by embedding the following script:

<script src="https://offen.mywebsite.org/script.js" data-account-id="<YOUR_ACCOUNT_ID>"></script>

In case you would use the script on a website running on an entirely different host domain, usage data would be collected for users that have third party cookies enabled only.

https protocol

Offen itself requires to be served using SSL. This enables us to guarantee data is being transmitted without the possibility of third parties intercepting any communication. In case you do not have a SSL certificate for your Offen subdomain, you can configure Offen to automatically request and periodically renew a free certificate from LetsEncrypt for the subdomain Offen is being served from. See the configuration article for how to use this feature.

In case you do have a SSL certificate for the domain you are planning to run Offen on (e.g. a wildcard certificate for your top domain), pass the certificate’s location to the runtime configuration and Offen will use the certificate. See the configuration article for information on how to do so.


While Offen can take care of itself being run using SSL, the protocol used to serve the host document also matters, as it defines whether browsers consider the execution context secure or not. This means that in case you serve your website using plain http, Offen will not be able to use native cryptographic methods for encrypting usage data and will fall back to userland implementations instead. This approach is heavy and slow and is not recommended.

Using SSL for your own site will be benefitial regarding lots of other aspects as well. You can check the LetsEncrypt website for plenty of information on how to get free and robust SSL for any setup.

Choosing a datastore

Offen requires a relational datastore to be available for it to store event and account data. By default, it will use a SQLite database that is stored on the host system. This works well and is a good choice if you do not serve very high amounts of traffic.

In case you want to scale Offen or need more performance you can also use a MySQL or Postgres database instead. See the configuration article for how to configure dialect and database location in such a setup.

Additional considerations

Running the application behind a reverse proxy

Offen itself is sufficiently hardened in order to be exposed to the public internet directly. If your setup requires running it behind a reverse proxy, you can do it, but we actively advise against doing so for the reason that the proxy will leave possibly unwanted traces like logs containing user IPs or similar. If the reverse proxy is not a hard requirement of your setup, leave it out.

Transactional email

Offen can email you a link to reset your account’s password in case you forgot it. The recommended way of doing so is configuring Offen with SMTP credentials (you might well be able to use your default mail credentials here).

In case you do not configure this, Offen falls back to a local sendmail installation if found, yet it is likely that these messages will never arrive at all due to system restrictions or third parties bouncing email sent using that channel. Do note that the sendmail fallback is not available in offen/offen Docker containers.