Deploy Infinite Scale on the Hetzner Cloud

Introduction

Install Infinite Scale using Docker Compose on the Hetzner Cloud for production use. The aim of this guide is to be up and running as fast as possible using a deployment setup that includes Infinite Scale and web office applications for document collaboration for home usage or small businesses. It also uses valid certificates from Letsencrypt.

Some decisions and steps need to be taken in order when setting up and configuring the server. We therefore highly recommend reading the guide and not just trying to copy paste commands.
With the decision to use Hetzner for our cloud deployment example, you can select from a variety of server locations which include many residing in the EU. Using a location inside the EU has a big positive impact for your data in terms of General Data Protection Regulation (GDPR).
With the minimum configuration available on Hetzner, you can start with about €4/month for a cloud driven Infinite Scale deployment. Note that prices are subject to changes and only intended for informational purposes.
This guide references the latest production version of Infinite Scale.
With this setup, each deployment only contains one instance of Infinite Scale.

Requirements

Hardware

This guide describes an installation of Infinite Scale on the Hetzner Cloud using Ubuntu LTS as OS and docker compose. The underlying hardware can be configured according to the offers from Hetzner and your requirements.

At minimum and at the time of writing, type CX22 (2 shared Intel CPU’s with 4GB RAM) with 40GB embedded space can be selected. The selection can be changed after deployment if more resources are needed.

  • Disk space
    About 2.4GB of disk space is needed for the default enabled services as you not only get Infinite Scale but also office packages for online collaboration and other required software to run this setup.

    • Depending on Hetzner’s offers, an embedded diskspace of 40GB is included as part of the server. When the server is reset, the diskspace and ALL of its data is lost. Consider configuring independent volumes which can be sized according your needs but are at an extra monthly charge. Note that you can start with embedded disk space and reconfigure afterwards. See the Volumes description for an explanation of the term volume.

  • Memory
    We recommend at minimum 4-6GB of memory.

Knowledge Stack

You, as administrator, must have the following minimum knowledge stack.

  • Being able to order cloud resources on Hetzner.

  • Being capable to order and configure external accessible domains.

  • Being capable to define firewall rules available on Hetzner.

  • Command line (bash) tools like:
    Key generation, ssh, actions on files, edit files etc.

  • Maintaining a server and installing software packages etc.

Software Stack

For the OS, Ubuntu LTS 24.04 has been selected.

Volumes

Volumes are the location where docker stores data. In a nutshell, docker can handle two types of volumes:

  • Volumes managed by docker:
    These volumes are managed by docker and are located, if not otherwise defined, in the same partition where the OS is installed. While this is easy to handle and does not need extra configuration, you have dependencies that should be considered like sharing space, snapshotting, resetting, backup/restore, migration etc.

  • External volumes:
    These volumes are not managed by docker. You need to provide docker a mount point for the volume which can be a folder, partition, external storage etc.

Note that the term volume can be used in different contexts. For example, Hetzner uses the term volume for a definable disk space that is independently provisioned and charged. Such a volume can then be connected to a docker volume to store data.

Other Requirements

Firewall

Because the server configured on Hetzner is exposed to the internet, we highly recommend configuring a firewall for security reasons. Hetzner provides a firewall configuration option right from the beginning, or is available after the server has been defined.

The minimum configuration for the firewall is to allow TCP port 22, 80 and 443. We also recommend to allow ICMP to be able to ping the server. Though possible, there is no need to configure an additional firewall inside the server.
Domain Name and Routing

To access Infinite Scale from the internet, you must:

  • Own a domain name which will get multiple subdomains configured.

    • You can also use a wildcard operator for the subdomains in the DNS configuration. In cases where you already use subdomains for other purposes, we recommend using a subdomain as entry point and add the wildcard operator there to allow different IP configurations.

  • The IP address provided by Hetzner needs to be used for the (sub)domains configured.

Note that you can use any domain provider of choice.

eMail

The following data needs to be available to configure the Infinite Scale eMail setup, see the notifications service for more details.

  • You must configure at minimum the SMTP_SENDER, even it is a dummy email like noreply@example.com, the deployment will not startup otherwise.

  • If all other email data is not available, Infinite Scale will start but no notifications can be sent.

  • SMTP_HOST
    SMTP host to connect to.

  • SMTP_PORT
    Port of the SMTP host to connect to.

  • SMTP_SENDER
    An eMail address that is used for sending Infinite Scale notification eMails like
    ocis <noreply@yourdomain.com>.

  • SMTP_USERNAME
    Username for the SMTP host to connect to.

  • SMTP_PASSWORD
    Password for the SMTP host to connect to.

  • SMTP_AUTHENTICATION
    Authentication method for the SMTP communication.

  • SMTP_SECURITY
    Define using secure or insecure connections to the SMTP server.

Domain Names

This environment requires that multiple (sub)domain names are available. You have to deviate from the examples according to your environment. The (sub)domains must be configured to point to the server you configured. The same is true when using a wildcard configuration. For a wildcard setup on the DNS, three (sub)domains must be provided to configure the .env file described in one of the next sections.

The following (sub)domains are required at minimum, an example is printed for each, replace them according to your environment:

  • OCIS_DOMAIN
    ocis.yourdomain.com

  • COLLABORA_DOMAIN
    collabora.yourdomain.com

  • WOPISERVER_DOMAIN
    wopiserver.yourdomain.com

Accessing Infinite Scale

Infinite Scale can be accessed from the internet and from your local network via a browser using the URL defined in OCIS_DOMAIN:

Network Overview

Limitations

Data Location

If not otherwise setup and configured, all data is stored in volumes managed by docker in the same partition of the server. If you want to define your own volume paths, provide the paths and configure them in the .env file accordingly. This is highly recommended for production environments and described in the Hardware and Volumes sections above.

User and User Access Management

The following embedded services are well suited for home use and smaller businesses though Infinite Scale can be configured to use external products which is relevant for bigger installations and not covered here.

  • Infinite Scale has an embedded identity management (IDM [1]) which takes care of creating, storing, and managing user identity information.

  • In addition, it also has an embedded identity provider (IDP [2]) to track and manage user identities, as well as the permissions and access levels associated with those identities.

Prepare Hetzner

SSH Key

We recommend using key-based authentication for ssh to access the configured server instead of using user and password. This is not only beneficial for security reasons but also because you can define the public key to be installed during the initial server configuration.

All OS

Follow the ssh-keygen guide to generate the required keys. We recommend, if possible, using the ed25519 algorithm and a passphrase for enhanced security. The keys to use after generation are located in ~/.ssh. Name the keys during the generation process accordingly to avoid overwriting existing ones.

Use the public key

  • During server setup described in one of the sections below, you can use the content of the public key file to setup ssh authentication when asked.

  • Alternatively, after the server has been created, you can copy the public key to the server by adding the contents of the generated <key>.pub file to the ~/.ssh/authorized_keys file manually. This step is necessary, because the server does not have password authentication which would be required to transfer the key by command.

Additionally for Windows

  • When using Putty to access your server, you must convert the private key generated into Putty’s ppk format. Read the puttygen guide for how to do so. You need to specify on each login the ppk file generated via Connection  SSH  Auth  Connections  Private key file.

  • When using the command shell with ssh to login or when using SCP, you must:

    • Have the private/public keys in C:\Users\<user>\.ssh\

    • Add the following to C:\Users\<user>\.ssh\config

      Host <the-servers-public-url-or-ip>
    PreferredAuthentications publickey
    PasswordAuthentication no
    IdentityFile C:\Users\<user>\.ssh\<private-key-name>

Login to Hetzner

If you do not already have an account on Hetzner, register for free and log in.

Hetzner Login or register

Configure and Order the Desired Server

After logging in, select from the selector on the top right the cloud item.

Select Cloud

Then, you either can use an existing project, if you have one, or create a new project.

Create new project

Select the project of choice and in the new screen click on Add Server.

In the following screen, you can define the

  • Server Location (Choose one from the offered)

  • Image (we use Ubuntu for this deployment)

  • Type (select any server type that matches your requirements)

  • Networking (we recommend using IPv4 as well as IPv6)

  • SSH keys (here you enter the public key you created before)

  • Volumes (add a volume if you want to separate the OS from the data, can be added later on too)

  • Firewall (add a rule for at minimum port 22, 80 and 443, can be added later on too)

  • …​ there can be more items not listed here, configure them according your needs.

  • Name (define a name for the server)

After you have finished, the server is built, and when done, you can click on it which opens a screen with more details and post-configuration options.

Server View
In this screen, you also see the IP address of the server that is necessary to be used for the domains pointing to this server.

Add the IP Address to the Domains

After the server has been finally setup, you must use the IP address assigned to this server to configure DNS mapping at your DNS provider accordingly. If you have allowed ICMP requests in the firewall settings, you can then ping your server with one of the domain names defined.

Prepare the Server

As a standard regular task, you need to update packages, especially after first server login. Open a shell on the server and issue the following command:

apt-get update && apt-get upgrade

Install Required Software Packages

Note that we do not recommend using the Ubuntu embedded Docker installations but install and upgrade them manually to get the latest releases.

Docker Engine

Follow this guide to install docker: Install using the apt repository.

Docker Compose

Follow this guide to install docker compose: Install the Compose plugin.

unzip

The package unzip may not be present. In case install with:

apt install unzip

Download and Transfer the Example

The client to download the example is not the server you upload to. The server does not have a graphical interface (GUI) and therefore no browser. The example commands below are based on a Linux client. If you are using macOS or Windows, the commands need to be adapted accordingly. This mainly effects the location the browser downloads to (~/Downloads).
The client from where you download the example via a browser and upload it using scp must have granted access to the server and have the scp app installed.

To download and extract the necessary deployment example [3], open a browser and enter the following URL:

https://download-directory.github.io?url=https://github.com/owncloud/ocis/tree/v5.0.9/deployments/examples/ocis_wopi

The .zip file will be downloaded into your local Download directory.

Transfer the .zip file created to the server by issuing the following command, replace root@182.83.2.94 with the username and address of the server according your setup:

scp ~/Downloads/'owncloud ocis v5.0.9 deployments-examples_ocis_wopi.zip' root@182.83.2.94:/opt

Note that the command differs a bit on Windows due to way how the home directory and the path separator is defined.

With the next step, if you have already unzipped that file before or if you intend to update an existing extract with a new compose version downloaded, the .env file will get overwritten without notice and you need to reconfigure this deployment!

Extract the Example

Login into the server and:

  • Create a subdirectory to save all compose files and folders.

    mkdir -p /opt/compose/ocis/ocis_wopi

  • Extract the zip file into the directory by issuing the following command:

    unzip -d /opt/compose/ocis/ocis_wopi \
  /opt/'owncloud ocis v5.0.9 deployments-examples_ocis_wopi.zip'

  • When files have been extracted, list the directory with:

    ls -la /opt/compose/ocis/ocis_wopi/

    The listing should contain files and folders like the following:

    config
docker-compose.yml
.env
README.md
collabora.yml
companion.yml
...

Edit the Configuration File

Change into the /opt/compose/ocis/ocis_wopi directory and open the .env file with an editor.

Only a few settings need to be configured:

  • INSECURE
    Comment this line because we are on an internet facing server.

  • TRAEFIK_ACME_MAIL
    Add a valid response eMail address for Letsencrypt, see the note below.

  • TRAEFIK_ACME_CASERVER
    Set the CAServer to staging, see the note below.

  • OCIS_DOMAIN, COLLABORA_DOMAIN and WOPISERVER_DOMAIN
    Set the domain names as defined in Domain Names.

  • OCIS_CONFIG_DIR and OCIS_DATA_DIR
    If you expect a higher amount of data in the instance, consider using own paths instead of using docker internal volumes.

  • SMTP_xxx
    Define these settings according to your eMail configuration. With the settings defined, Infinite Scale is able to send notifications to users. If the settings are not defined, Infinite Scale will start, but notifications can’t be sent.

When not defining your own domain names, internal evaluation only domain names with self-signed certificates are used automatically.
Additional options can be configured like web apps. These should be configured after successfully starting the deployment without issues. This eases finding any first startup issues that need to be solved first.

When the configuration is completed, you can optionally print the final assembled docker compose yml setup before starting it by using the following command. This output helps finding configuration issues more easily.

docker compose config

Certificate Generation Process

The recommended process to generate live certificates is the following:

  1. First, let LetsEncrypt generate "fake" certificates. These certifcates show that the process works but they cant be used in production. To do so, the environment variable TRAEFIK_ACME_CASERVER needs to be set to LetsEncrypt’s Staging Environment, see the .env file for the value to be set. By doing so, any restart after fixing issues will not count against the rate limit of LetsEncrypt.

  2. The TRAEFIK_ACME_MAIL must be set to a valid eMail address you own. When certificate issuing is triggered, LetsEncrypt checks in the request for creating valid certificates, if the response eMail address is valid and continues if so. If not, it logs an error and self-signed certificates are being used, see see Solving First Startup Issues.

  3. Start the Deployment.

  4. Then, if any issues occur, you need to Stop the Deployment and fix them before continuing with the next step. See Solving First Startup Issues for a list of common issues,

  5. Finally, if there are no (more) issues which you can identify because Fake LE intermediate X1 certificates have been generated (check the certificate issuer in the browser, Google for how to do so), you must delete the cert-volume and set back the TRAEFIK_ACME_CASERVER environment variable to empty and startup the instance as described below.

Start the Deployment

When you have finished the configuration, you can start the deployment by issuing the following command:

docker compose up -d

This command will download all necessary containers and starts up the instance according your settings in the background (flag -d).

Check the logs

If no issues are logged, traefik and LetsEncrypt were able to handle connectivity and domains.

In case you have used staging certificates as suggested above,

When done, recheck the traefik logs and when all is fine, you can access your instance, see First Time Login.

Solving First Startup Issues

Note, see Monitor the Instance for more details on logging.

If any issues are logged by traefik on first startup with respect to LetsEncrypt like:

Common issues

  • …​Contact emails @example.org are forbidden:
    The environment variable TRAEFIK_ACME_MAIL needs to be set to a valid eMail address you own.

  • …​unable to generate a certificate for the domains…​, acme: error: 400 and acme-challenge:
    Check if the TCP ports 80/443 are open in the firewall configured. You can run a test during running compose to test if traefik can be reached on those ports. To do so visit Let’s Debug.

  • …​DNS problem: NXDOMAIN looking up A for…​
    This points to a DNS resolution problem. Check if the domains entered in the DNS and in the .env file match. Note that when using wildcard domains on the DNS, the fixed part must match on both sides.

For any issue fixed, before you bring up the instance again, some steps need to be taken. This is because the certificate volume now holds invalid data:

Post fixing the issue

The following actions need to be taken before starting the deployment again:

Shut down the deployment
docker compose down

Note, do not use the -v option as it will delete ALL volumes.

List the docker volumes
docker volume ls
Delete the docker certs volume
docker volume rm ocis_wopi_certs

Stop the Deployment

Stopping the deployment is easy, just issue:

docker compose down --remove-orphans

For safety reasons, do not add the -v (volumes) flag to the command as that would delete all volumes including their data. If deleting volumes is necessary, deleting them selectively is the preferred method, see the section above for an example. See the docker compose down options for more details.

Change Settings

To change settings via the .env file, the deployment must be in the down state. See the section above for how to do so.

First Time Login

Now, after preparations have finished, you can access your instance from any client. To do so, open your browser and enter the instance URL as you have defined it:

ocis.yourdomain.com

Which will show the following screen:

Infinite Scale Login

For the credentials, use:

  • admin as user and

  • admin for the password,
    or the one you have defined manually during setup.

If you have defined an initial password via the .env file manually but forgot it, you need to follow one of the procedures described in the Admin Password section.

If you have logged in successfully, you should see the following screen:

Infinite Scale Logged In

Congratulations, you have successfully setup Infinite Scale with Web Office.

Checkout the Desktop App or Mobile Apps to sync files to/from clients.
The Infinite Scale deployment will reboot automatically on a server reboot if the compose environment is not shut down by command.

Among other topics described below, some basic monitoring commands are provided.

Monitor the Instance

Container

To get the state and the Container ID, issue one of the following commands:

Long form, this command will print the required Container ID, among other data
docker ps -a
Short form with only the Service name, State and Container ID, needs to be issued in /opt/compose/ocis/ocis_wopi:
docker compose ps -a --format "table {{.Service}}\t{{.State}}\t{{.ID}}"

Logs

Issue the following command to monitor a log:

Replace the <container_id> according to the container for which you want to monitor the log.
docker logs -f <container_id>

Admin Password

Initial Admin Password from Docker Log

If the manually set initial admin password has been forgotten before it got changed, you can get it from the docker log. See the View container logs for more details on docker logging.

First you need to get the Infinite Scale CONTAINER ID:

docker compose ps -a --format "table {{.Service}}\t{{.State}}\t{{.ID}}"

From the output, see an example below, note the container ID that matches ocis:

SERVICE         STATE     CONTAINER ID
collabora       running   a7f74dfbbec3
collaboration   running   ed4d086ddd06
ocis            running   b395d936c23a
tika            running   08ae7b0c9c0e
traefik         running   5f0e1d03bcbf

Use the container ID identified in the following command to read the Infinite Scale logs to get the initial admin password created, replace <CONTAINER ID> accordingly:

docker logs <CONTAINER ID> 2>&1 | less

The output prints the log from the beginning. As first entry, the initial admin password set during first startup is shown. You can scroll thru the log using the keyboard, see the less description for more details.

If no password can be identified, you must reset the admin password via the command line as described below.

Command Line Password Reset

To change the admin password from the command line, which you can do at any time, follow the guide described in Password Reset for the Admin User.

Volume Migration

This section gives some guidance if you want to migrate the Infinite Scale docker internal volumes to docker volumes using a local path. For example, this can be required to separate the container from its data or if a high data volume is expected. See additional documentation in the Start a Service After a Resource is Mounted if you want to use network mounts like NFS or iSCSI for the data directory.

  • Prepare two directories which will provide the mount point for Infinite Scale data and config.
    The example will use the local path /mnt/data and mnt/config, adapt according your environment.

  • For the following steps, the deployment must be in the up state, the containers must provide a container ID for copying.

    • Stop the running instance. By doing so, the instance gets stopped but containers are not removed compared to when downing it:

      docker compose stop

    • Get the ocis container ID using one of the maintenance - Container commands.

    • Copy both the content of the docker internal ocis-config and ocis-data volume to their new local location by issuing the following commands, replace <CONTAINER ID> accordingly:

      docker cp <CONTAINER ID>:/etc/ocis/. /mnt/config
docker cp <CONTAINER ID>:/var/lib/ocis/. /mnt/data

    • Change the ownership of the new source folders recursively. This step is very important because the user inside the container is 1000 and will mostly not match the user who copied the folders:

      chown -R 1000:1000 /mnt/config /mnt/data

  • Down the compose instance by issuing:

    docker compose down

    • In the .env file, set the paths:

      OCIS_DATA_DIR=/mnt/data
OCIS_CONFIG_DIR=/mnt/config

  • Bring the compose environment up with:

    docker compose up

    • If the containers come up without reporting issues, you have successfully moved your Infinite Scale docker internal volumes to local paths.

  • Finally, you can remove the docker internal volumes for config and data:

    docker volume ls
docker volume rm ocis_wopi_ocis-config ocis_wopi_ocis-data

Updating

Note that this deploymment can currently only be updated within Infinite Scale v5.

If a new Infinite Scale v5 version is available, just down the compose environment and bring it back up. Containers will update automatically and you can continue using Infinite Scale as usual.

Certificate Renewal

There is nothing special to do renewing certificates issued. Traefik takes care of the renewal process automatically. In case of a renewal issue, just restart the compose environment as Traefik checks certificate expiry on startup.

Updating

Note that this deploymment can only be updated within Infinite Scale v5.

If a new Infinite Scale v5 version is available, you must stop the compose environment with docker compose down, pull the new image with docker compose pull and start the compose environment with docker compose up -d again. You can use the latest tag in the OCIS_DOCKER_TAG variable as it will automatically point to the latest available production release.


1. See the IDM service for more details
2. See the IDP service for more details
3. Derived from the ocis_wopi developer example