Deploy Infinite Scale on the Hetzner Cloud for Production Use
- Introduction
- Requirements
- Accessing Infinite Scale
- Limitations
- Prepare Hetzner
- Add the IP Address to the Domains
- Prepare the Server
- Download and Transfer the Example
- Extract the Example
- Edit the Configuration File
- Start the Compose Setup
- Stop the Compose Setup
- Change Settings
- First Time Login
- Monitor the Instance
- Admin Password
- Volume Migration
- Updating
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.
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 rolling version 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.
|
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 SW packages etc.
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 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.
-
-
The following data needs to be available to configure the Infinite Scale eMail setup, see the notifications service for more details. Note that if this 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
Note that more (sub)domains may be required depending on your setup. See the .env
file more details.
Accessing Infinite Scale
Infinite Scale can be accessed from the internet and from your local network with the OCIS_DOMAIN
you have defined:
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 as described in the Hardware section 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.
Follow the ssh-keygen guide to generate the required keys. We recommend, if possible, using the ed25519
algorithm. The keys to use after generation are located in ~/.ssh
.
When using Putty (Windows) to access your server, you must convert the private key generated into the ppk
format to be usable for Putty. Read the puttygen guide to do so.
After the server has been created, you can copy new private keys to the server by adding them into the ~/.ssh/authorized_keys
file.
Configure and Order the Desired Server
After logging in, select from the selector on the top right the cloud
item.
![Select Cloud](../../_images/depl-examples/ubuntu-compose/hetzner-select-cloud.png)
Then, you either can use an existing project, if you have one, or create a new project
.
![Create new project](../../_images/depl-examples/ubuntu-compose/hetzner-create-new-project.png)
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)
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)
-
… more items
-
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](../../_images/depl-examples/ubuntu-compose/hetzner-server-defined.png)
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:
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
Note that the client from where you download the example and upload it via scp
must both have granted access to the server and the scp
app installed. For the scp
example, a Linux based client has been selected. Adapt the command according the OS used.
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/v6.3.0/deployments/examples/ocis_full
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 the user accordingly:
scp '~/Downloads/owncloud ocis v6.3.0 deployments-examples_ocis_full.zip' <user>@<IP or domain>:/opt
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_full
-
Extract the zip file into the directory by issuing the following command:
unzip -d /opt/compose/ocis/ocis_full \ /opt/'owncloud ocis v6.3.0 deployments-examples_ocis_full.zip'
-
When files have been extracted, list the directory with:
ls -la /opt/compose/ocis/ocis_full/
The listing should contain files and folders like 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
andWOPISERVER_DOMAIN
Set the domain names as defined in Domain Names. -
OCIS_CONFIG_DIR
andOCIS_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.
|
Start the Compose Setup
When you have finished the configuration, you can start the compose setup by issuing the following command:
docker compose up -d --remove-orphans
This command will download all necessary containers and starts up the instance according your settings in the background (flag -d
).
Check the logs via the docker logs command
, especially the traefik logs. See the Monitor the Instance for more details on logging.
If no issues are logged, traefik and LetsEncrypt were able to handle connectivity and domains. In case you have used staging certificates as suggested, down the compose environment, change the setting, remove the cert
volume as described below and restart the compose environment. Recheck the traefik logs and when all is fine, you can access your instance.
Solving First Startup Issues
If any issues are logged by traefik on first startup with respect to LetsEncrypt like:
-
…unable to generate a certificate for the domains…
,acme: error: 400
andacme-challenge
:
Check if the 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.
If you have a DNS issue at this stage or you have used the Letsencrypt staging environment, you will face follow-up issues on a consecutive compose start because the certificate volume now holds invalid data. Therefore, the cert
volume needs to be deleted:
docker compose down
Note, do not use the -v
option as it will delete ALL volumes.
docker volume ls
docker volume rm ocis_full_certs
Stop the Compose Setup
Stopping the compose setup is easy, just issue:
docker compose down
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.
Change Settings
To change settings via the .env
file, the compose setup 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](../../_images/depl-examples/ubuntu-compose/infinite-scale-login.png)
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](../../_images/depl-examples/ubuntu-compose/infinite-scale-logged-in.png)
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 and a short description to update Infinite Scale is provided.
Monitor the Instance
Container
To get the state and the Container ID, issue one of the following commands:
docker ps -a
docker compose ps -a --format "table {{.Service}}\t{{.State}}\t{{.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
andconfig
.
The example will use the local path/mnt/data
andmnt/config
, adapt according your environment. -
For the following steps, the compose setup 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
andocis-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
anddata
:docker volume ls docker volume rm ocis_full_ocis-config ocis_full_ocis-data
Updating
Note that this deploymment can, for the time being, only be updated within Infinite Scale rolling releases.
If new Infinite Scale releases are available, you must not skip any version in between the current running and the latest available release for internal upgrade reasons. All versions need to be downloaded and started one time. For more details see the Updating and Overlap description in the developer documentation.
-
If there is no release gap, you can update by just stopping and starting the compose environment.
-
For any release gap, you must stop the compose environment with
docker compose down
, set theOCIS_DOCKER_TAG
variable in the.env
file accordingly, pull the new image withdocker compose pull
and start the compose environment withdocker compose up -d
again. For the last release, you can remove any setting ofOCIS_DOCKER_TAG
aslatest
is used by default.