Setting up and using subdomains


Table of contents

  1. Same-origin policy and 1st party cookies
  2. A and CNAME records
  3. Using one Offen installation for multiple sites
    1. Configuring AutoTLS for multiple sites

Same-origin policy and 1st party cookies

Offen is designed to leverage the Same-origin policy and usage of 1st party cookies only to make sure usage data is handled securely and protected from unwanted access by 3rd party scripts on your site or similar, at all times.

In practice, this boils down to the following setup: if you are using your Offen instance for collecting usage data on a site www.yoursite.org, Offen is expected to be served from a subdomain of yoursite.org, e.g. offen.yoursite.org or analytics.yoursite.org (the exact name of the subdomain does not matter). This makes sure Offen can securely collect usage data of all visitors that opt in to data collection.

In case you would be using a different top level domain for your Offen installation (e.g. offen.example.com), Offen would be limited to user agents that accept 3rd party cookies, which is a concept that is luckily fading away quickly.

Heads Up

You should not try to rewrite your Offen server to www.yoursite.org/offen/ or similar. This could theoretically work with proper rewrite magic applied, but would expose usage data to 3rd party scripts. Use a subdomain instead.

A and CNAME records

The most common ways for configuring your subdomain with your DNS provider (this might be a dedicated DNS provider or it is included in your hosting package) is by setting A or CNAME records that point to your Offen instance.

If you access your installation using an IP address you will usually set an A record, whereas a CNAME is an alias for another hostname you might be using.

Refer to your providers documentation for instructions on how to do this.

Using one Offen installation for multiple sites

One Offen instance can be used to serve multiple accounts on different domains. Say for example you are using Offen to collect usage data for multiple customers, you can point multiple DNS records to the same instance and use it for each of these customers.

E.g. if you have three sites, www.yoursite.org, www.anothersite.org and www.somethingelse.org, you can point the DNS records for offen.yoursite.org, offen.anothersite.org and offen.somethingelse.org to the same Offen instance, allowing you to leverage the same-domain benefits for each of these sites, while still only running a single instance.

By design, consent is valid for a single domain only, so users will have to opt in for data collection on each of these domains.

When logging in, data for all three sites will be available for you to analyze in the same session.

Heads Up

When embedding the Offen script on sites in such a setup, make sure it is using the correct domain.

Configuring AutoTLS for multiple sites

If your Offen installation serves multiple domains, you will need to provide SSL certificates for each of them. Offen can acquire free and self-renewing certificates from LetsEncrypt for you when you specify these as a comma separated list in the OFFEN_SERVER_AUTOTLS configuration value:

OFFEN_SERVER_AUTOTLS="offen.yoursite.org,offen.anothersite.org,offen.somethingelse.org"

Heads Up

Offen cannot acquire certificates for you when it is running behind a loadbalancer. We recommend exposing Offen to the public internet directly, opening ports 80 and 443 and using the AutoTLS feature.