Deploy Infinite Scale on the Hetzner Cloud

Introduction

Install Infinite Scale using Docker Compose on the Hetzner Cloud for production use. The goal of this guide is to get you up and running as quickly as possible with a deployment setup that includes Infinite Scale and Web Office document collaboration applications for home or small business use. It also uses valid certificates from Letsencrypt.

There are several decisions and steps that need to be taken when setting up and configuring the server. We strongly recommend that you read the manual and not just try to copy and paste commands.
By choosing Hetzner for our cloud deployment example, you can choose from a variety of server locations, many of which are located in the EU. Using a location within the EU has a big positive impact on your data in terms of the 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 rolling 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
    Approximately 2.4GB of disk space is required for the default enabled services, as this setup provides not only Infinite Scale, but also office suites for online collaboration and other required software.

    • Depending on Hetzner’s offerings, 40GB of embedded disk space is included as part of the server. If the server is reset, the disk space and ALL of its data will be lost. Consider configuring independent volumes that can be sized to your needs, but for an additional monthly fee. Note that you can start with embedded disk space and reconfigure later. See the Volumes description for an explanation of the term volume.

  • Memory

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

    • If you plan to enable antivirus scanning, see the memory consideration section in the antivirus service for additional memory requirements.

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 where Docker stores data. In short, Docker can handle two types of volumes:

  • Volumes managed by docker:
    These volumes are managed by Docker and, unless otherwise specified, are located in the same partition where the operating system is installed. While this is easy to use and requires no additional configuration, there are dependencies that should be considered, such as space sharing, snapshots, resetting, backup/restore, migration, etc.

  • External volumes:
    These volumes are not managed by Docker. You must provide Docker with 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, as a provider of computing resources, uses the term volume to refer to a definable disk space that is independently provisioned and billed. Such a volume can then be attached 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 an entry point and adding the wildcard operator there to allow for 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 is required to configure the Infinite Scale eMail setup, see the notifications service for more details.

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

  • 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 multiple (sub)domain names to be available. You will need to modify the examples to suit your environment. The (sub)domains must be configured to point to the server you are configuring. The same applies if you are 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 as a 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

Note that depending on your setup, more (sub)domains may be required. See the .env file for more details..

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

Unless otherwise set up and configured, all data is stored in volumes managed by Docker on 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. This is highly recommended for production environments and is described in the Hardware and Volumes sections above.

User and User Access Management

The following embedded services are well suited for home and small business use, although Infinite Scale can be configured to use external products that are relevant to larger installations and are not covered here.

  • Infinite Scale has an embedded identity management (IDM [1]) that 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 that you use key-based authentication for ssh to access the configured server, rather than using a user and password. This is not only beneficial for security reasons, but also because you can specify 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 using the ed25519 algorithm and a passphrase for increased security. The keys to be used after generation are located in ~/.ssh. Rename the keys during the generation process to avoid overwriting existing keys.

Use the public key

  • During the server setup described in one of the sections below, you can use the contents of the public key file to set up ssh authentication when prompted.

  • Alternatively, after the server has been created, you can copy the public key to the server by manually adding the contents of the generated <key>.pub file to the ~/.ssh/authorized_keys file. 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

  • If you are using Putty to access your server, you will need to convert the generated private key to Putty’s ppk format. See the puttygen guide for how to do this. You must specify the ppk file generated via Connection  SSH  Auth  Connections  Private Key File on each login.

  • If you are using the command shell with ssh to log in, or if you are 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 at Hetzner, register for free and log in.

Hetzner Login or register

Configure and Order the Desired Server

After logging in, select cloud from the drop-down menu at the top right.

Select Cloud

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

Create new project

Select the project of your 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)
    This can be done at any time after the first setup but needs data migration. The volumes defined can then be used by configuring variables in the .env file

  • 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)

When finished, the server will be built and you can click on it to open a screen with more details and post-configuration options.

Server View
This screen also shows the IP address of the server that must be used for the domains pointing to this server.

Add the IP Address to the Domains

Once the server is finally set up, you will need to use the IP address assigned to this server to configure DNS mapping at your DNS provider. If you have allowed ICMP requests in your firewall settings, you can then ping your server using one of the defined domain names.

Prepare the Server

As a standard periodic task, you will need to update packages, especially after the 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 as they may be outdated, but rather installing and upgrading them manually to get the latest versions.

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 unzip package may not be available. In this case, install with:

apt install unzip

Download and Transfer the Example

The client that downloads the example is not the server that you upload to. The server does not have a graphical user interface (GUI) and therefore does not have a browser. The sample commands below are based on a Linux client. If you are using MacOS or Windows, you will need to modify the commands accordingly. This mainly affects the location where the browser downloads to (~/Downloads).
The client from which you download the example via a browser and upload it using scp must have access to the server and have the scp application 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/v7.1.2/deployments/examples/ocis_full

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

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

scp ~/Downloads/'owncloud ocis v7.1.2 deployments-examples_ocis_full.zip' root@182.83.2.94:/opt

Note that the command is slightly different on Windows due to the way the home directory and path separator are defined.

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

Extract the Example

Login into the server and:

  • Create a subdirectory to store all Compose files and folders.

    mkdir -p /opt/compose/ocis/ocis_full

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

    unzip -d /opt/compose/ocis/ocis_full \
  /opt/'owncloud ocis v7.1.2 deployments-examples_ocis_full.zip'

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

    ls -la /opt/compose/ocis/ocis_full/

    The list should contain files and folders such as the following:

    clamav.yml
cloudimporter.yml
collabora.yml
config
...

Edit the Configuration File

Change into the /opt/compose/ocis/ocis_full 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_DOCKER_IMAGE
    Check that the correct image type is selected (rolling).

  • 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. If the settings are defined, Infinite Scale will be able to send notifications to users. If the settings are not defined, Infinite Scale will start but won’t be able to send notifications.

If you do not define your own domain names, only domain names with self-signed certificates are automatically used for internal evaluation.
Additional options can be configured like web applications. These should be configured after the deployment has successfully started without problems. This makes it easier to find any initial startup issues that need to be resolved first.

When the configuration is complete, you can optionally print the final assembled Docker compose yml setup before running it by using the following command. This output will help you troubleshoot configuration issues.

docker compose config

Certificate Generation Process

The recommended process for generating live certificates is as follows:

  1. First, have LetsEncrypt generate "fake" certificates. These certificates show that the process works, but they cannot be used in production. To do this, set the TRAEFIK_ACME_CASERVER environment variable to LetsEncrypt’s Staging Environment, see the .env file for the value to set. This will ensure that any restarts after fixing problems will not count against LetsEncrypt’s rate limit.

  2. The TRAEFIK_ACME_MAIL must be set to a valid email address that you own. When certificate issuance is triggered, LetsEncrypt checks in the request to create valid certificates if the response email address is valid and proceeds if it is. If not, it logs an error and uses self-signed certificates, see Solving First Startup Issues.

  3. Start the Deployment.

  4. If any problems occur, you must Stop the Deployment and fix them before proceeding to the next step. See Solving First Startup Issues for a list of common issues.

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

Start the Deployment

Once you have completed the configuration, you can start the deployment by issuing the following command:

docker compose up -d

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

Check the logs

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

If you used staging certificates as suggested above,

When this is done, check the traefik logs again, and if all is well, 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 problems are logged by traefik on first start with respect to LetsEncrypt like:

Common issues

  • …​Contact emails @example.org are forbidden:
    The environment variable TRAEFIK_ACME_MAIL must be set to a valid e-mail address that you own.

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

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

For each problem that is fixed, there are a few steps that must be taken before you can start the instance again. This is because the certificate volume now contains invalid data:

Post fixing the issue

The following actions must be taken before restarting the deployment:

Shut down the deployment
docker compose down

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

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

Stop the Deployment

Stopping the deployment is easy, just issue:

docker compose down --remove-orphans

For safety’s sake, do not add the -v (volumes) flag to the command, as this will delete all volumes, including their data. If deleting volumes is necessary, selective deletion is the preferred method, see the above section 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 this.

First Time Login

Now that the preparations are complete, you can access your instance from any client. To do this, open your browser and enter the instance URL as you 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 manually set an initial password via the .env file, but have forgotten it, you must 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 set up Infinite Scale with Web Office.

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

Among other topics described below, some basic monitoring commands and a brief description of update Infinite Scale 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_full:
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 was forgotten before it was changed, you can get it from the docker log. See View container logs for more details on docker logs.

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. The first entry is the initial admin password set at the first startup. You can scroll through the log using the keyboard, see less description for more details.

If the password cannot be determined, you must reset the admin password from 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 instructions in Password Reset for IDM Users.

Volume Migration

This section provides some guidance if you want to migrate the Infinite Scale Docker internal volumes to Docker volumes using a local path. For example, this may be necessary to separate the container from its data, or if a large amount of data is expected. See additional documentation in the Start a Service After a Resource is Mounted if you want to use network mounts such as NFS or iSCSI for the data directory.

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

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

    • Stop the running instance. This will stop the instance, but will not remove any containers, unlike shutting down the instance:

      docker compose stop

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

    • Copy the contents of both the Docker internal ocis-config and ocis-data volumes to their new local locations by issuing the following commands, replacing <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 most likely not be 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 -d

    • If the containers start up without any problems, 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_full_ocis-config ocis_full_ocis-data

Updating and Upgrading

Updating

Infinite Scale

For Infinite Scale rolling releases, the following steps are essential to avoid breaking the setup. This is because rolling releases depend on all updates being done in sequence.

When new versions of Infinite Scale are available, you may skip any version between the one you are currently running and the latest available rolling release for internal update reasons. All versions must be downloaded and launched at once. For more details, see Updating and Overlap in the developer documentation.

  • Each upgrade consists of a set of commands:

    sudo docker compose down \
sudo docker compose pull \
sudo docker compose up -d --remove-orphans

  • If there is no release gap, run the command block once.

  • * For any release gap, you need to run the command block from above once and set the appropriate release in the OCIS_DOCKER_TAG before pulling. Do not use a value for the last release, it defaults to latest.

  • Check if there are any changes to the Infinite Scale configuration. To do this, run an ocis init --diff plus apply any patches. The detailed how-to is described in the Upgrading Infinite Scale for 7.0.0. When done, restart the deployment.

  • Finally, you can remove old images if they are no longer in use.

Note that we recommend manually checking to see if the deployment source has changed. If it has, stop the deployment, backup your existing deployment source/configuration and update the deployment sources, then reapply your configuration settings and run the deployment.

Update non-Infinite Scale Images

Some images used do not have a specific release defined, but use latest. These images can be updated when new releases are available, for example for security or bug fixes. To do this, use the following commands:

sudo docker compose pull \
sudo docker compose up -d --remove-orphans

Upgrading

For all Infinite Scale major and minor releases, including previous rolling to production

  • Stop the deployment with:

    sudo docker compose stop

  • When upgrading from rolling to production, change the OCIS_DOCKER_IMAGE environment variable from owncloud/ocis-rolling to owncloud/ocis in the .env file.

  • Follow the appropriate Upgrading Infinite Scale guide.

  • Backup your existing deployment source/configuration and update the deployment sources - if they have been changed, reapply your configuration settings.

  • Re-pull the deployment. This will update all images with any versions that may have changed.

    sudo docker compose pull

  • Start the deployment.

    sudo docker compose up -d --remove-orphans

Certificate Renewal

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


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