Bare Metal Deployment with systemd
Introduction
This guide describes an installation of Infinite Scale as a systemd service on bare metal. This ranges from a small installation on a Raspberry Pi up to installations on a decent server.
This deployment example addresses a small production environment. For a minimal test and development environment, see the Minimal Bare Metal Deployment. The main differences between the setup described in this document and a minimal test environment is, the use of systemd, letsencrypt and a reverse proxy.
Note that this guide expects that prerequisite of a computer with an installed Linux distribution of choice is met and required software other than Infinite Scale is installed and preconfigured. There is no detailed explanation but, where possible, links for more information are provided.
This guide was tested on a Debian 11 (bullseye) host but should work on any other modern Linux system with systemd.
The embedded IDM service provides a minimal LDAP service for Infinite Scale and does not replace a LDAP server. See the IDM Service Configuration for details. |
Consider to extend the configuration described based on the information given in Graceful Shutdown. |
Requirements
-
A supported filesystem according the ocis prerequisites.
-
A HTTP reverse proxy, there are examples using nginx and Apache
-
Certbot + the nginx or Apache plugin
-
For certbot, there are many command line options available supporting common tasks like increasing security measures or automatic redirection, the example commands are limited to the minimum issuing a certificate. This includes that configuration files and security measures need to be applied manually.
-
With respect to security, some of the measures are shown in examples but not all possibilities are covered.
-
If using certbot command line options, files may be split by port and content can differ, though the result when combined is the same.
-
Excluded Tasks
There are a few steps that are recommended but not covered in this guide:
-
Automate the Let’s Encrypt certificate renewal via cron jobs
-
Install and set up a firewall
Used Settings
The following settings were used in this guide. You can change this according your needs:
-
The Infinite Scale binary location:
/usr/local/bin
(OS default) -
The Infinite Scale configuration directory:
/etc/ocis
-
The Infinite Scale base data directory:
/var/lib/ocis
-
The URL accessing Infinite Scale:
ocis.example.com
Note that this URL must resolve to the server running this installation. -
The internal port accessing Infinite Scale: 9200 (default)
Install and Prepare Infinite Scale
Install and Configure the Infinite Scale Binary
-
Download and install the Infinite Scale binary. To get the stable binary from ownCloud, visit download.owncloud.com, select the version and the platform of choice and copy the link of the file. Replace
<file_url>
and<file_name>
in the commands accordingly.Download the binary:
sudo wget -P /usr/local/bin <file_url>
-
Make the binary executable with:
sudo chmod a+x /usr/local/bin/<file_name>
-
Create a link from the versioned ocis binary name to the final executable named
ocis
:
Note when using a symbolic link like this, upgrading and/or testing is much easier.sudo ln -s -f /usr/local/bin/<file_name> /usr/local/bin/ocis
-
Check the version installed:
ocis version --skip-services
The output looks like this:
Version: 5.0.9 Compiled: 2024-10-24 00:00:00 +0000 UTC
Note that if you omit
--skip-services
, you will get additional information about services printed.
If you already have a running instance, you must stop and restart the instance to activate the new version. |
Create a Service User
-
In your operating system, create a user and group who will run the ocis service and own all the files of the Infinite Scale service but is not allowed to log in, has no shell and no home directory.
sudo useradd --system --no-create-home --shell=/sbin/nologin ocis
Infinite Scale Data Directory
-
Create the ocis data directory. All system data will be stored here including all files uploaded by the users.
sudo mkdir -p /var/lib/ocis
-
Make the service user
ocis
the owner of the data directory.sudo chown ocis:ocis /var/lib/ocis
Infinite Scale Configuration File
-
Create a directory and config file necessary for ocis. For security reasons, this user should have restricted permissions for this directory:
sudo mkdir -p /etc/ocis
sudo touch /etc/ocis/ocis.env
sudo chown -R ocis:ocis /etc/ocis
-
Create the environment file
/etc/ocis/ocis.env
with the following content. Adjust theOCIS_URL
variable to hold your domain where Infinite Scale will be reachable vianginx
. Add the correct port toOCIS_URL
if it deviates from the default port 443 likehttps://ocis.example.com:4242
. See the General Information section for more information about the environment variables used.sudo vi /etc/ocis/ocis.env
OCIS_URL=https://ocis.example.com PROXY_HTTP_ADDR=0.0.0.0:9200 PROXY_TLS=false OCIS_INSECURE=false OCIS_LOG_LEVEL=warn OCIS_CONFIG_DIR=/etc/ocis OCIS_BASE_DATA_PATH=/var/lib/ocis
PROXY_TLS
is set tofalse
because TLS termination will be done by the webserver. Though you also can secure the communication between Infinite Scale and the webserver, this is not covered by this document. -
Setting the correct
OCIS_URL
is essential for the built-in openIDConnect IDP as the IDP service needs to be reachable under the same host and port as the reverse proxy is configured. If this has not been configured the same, the IDP service will log errors likeorigin does not match request URL
. See the Using the Embedded IDP Service for configuration notes of thePROXY_TLS
environment variable.See the important notes for Configurations to Access the Web UI. -
Generate the initial Infinite Scale configuration file, also see The ocis init Command:
sudo -u ocis ocis init --config-path /etc/ocis
You will be asked if you want to configure Ininite Scale with certificate checking disabled. You can safely answer
yes
. Infinite Scale is composed of several microservices which encrypt the communication between them with TLS. By answering withyes
the communication is still encrypted but client and server certificates aren’t checked for validity. Usually this is good enough. For an extra secure deployment, provide a verifiable TLS certificate and enable certificate checking.The command when run successfully will show you the initial admin user’s password. Write it down somewhere safe so that you can log in when the setup is complete. The password can be changed in the UI later on or be reset if forgotten via Password Reset for the Admin User. This command will create the configuration file
/etc/ocis/ocis.yaml
.Do NOT delete the ocis.yaml
file without creating a backup of it first. When you regenerate theocis.yaml
file, it will be out of sync with the stored user data in the ocis data directory/var/lib/ocis
. If for some reason you still want to regenerate the config file, you first need to empty the data directory but beware if you already have user files stored there. Also see The ocis init Command for more details.
Setup the systemd Service
-
To run the Infinite Scale runtime as a systemd service, create the file
/etc/systemd/system/ocis.service
with the content provided below. The easiest way to do this is with the following command:sudo systemctl edit --force --full ocis.service
Then copy the content of the systemd file below into the editor and save it.
systemd file[Unit] Description=OCIS server [Service] Type=simple User=ocis Group=ocis EnvironmentFile=/etc/ocis/ocis.env ExecStart=/usr/local/bin/ocis server Restart=always [Install] WantedBy=multi-user.target
Run the following command to apply your changes:
sudo systemctl daemon-reload
Now you can run Infinite Scale as a systemd service. Start it with:
sudo systemctl enable --now ocis
With this setup, Infinite Scale is also restarted automatically after a reboot.
If you need to restart Infinite Scale because of configuration changes in
/etc/ocis/ocis.env
, run:sudo systemctl restart ocis
The systemd logs of Infinite Scale can be displayed by issuing:
sudo journalctl -f -u ocis
Dependent Infinite Scale Service Startup
If you want to ensure that you have a necessary service like a NFS mount point up and running before the Infinite Scale service starts up, see Start a Service After a Resource is Mounted.
This step can be an important measure, because if the Infinite Scale service starts up but the necessary mount point is not available, you may be in an undefined Infinite Scale operating state. |
Nginx as Reverse Proxy
Whenever a configuration change has been made, you need to do a configuration check and reload the nginx configuration. This can be done with two methods as described below. Select your preferred one. For ease of writing, the examples show sudo nginx -s reload .
|
-
sudo nginx -s reload
Note that this command includes checking and reloading the config in the same step.
-
sudo nginx -t
sudo systemctl reload nginx
Note that using
systemctl reload nginx
alone will NOT validate your configuration but will execute the command in a clean environment and not in the current user environment.
Prepare nginx for certbot
-
To set up nginx as a reverse proxy with Let’s Encrypt TLS certificates, create a file called e.g.
ocis
under/etc/nginx/sites-available
with the following content:server { listen 80 ; listen [::]:80 ; server_name ocis.example.com; }
-
Activate the new nginx config:
sudo ln -s -f /etc/nginx/sites-available/ocis /etc/nginx/sites-enabled/ocis
-
Check the config and reload nginx:
sudo nginx -s reload
Issuing a Certificate via certbot for nginx
-
Run
certbot
to issue the TLS certificates:sudo certbot --nginx -d ocis.example.com
Finalize the nginx Configuration
-
Adapt the config to redirect automatically to https, use the newly generated certificates and add the required proxy configuration. The full config should look like this:
server { listen 80 ; listen [::]:80 ; server_name ocis.example.com; # location to redirect to https location / { # add port if deviates via OCIS_URL return 301 https://$server_name$request_uri; } } server { # default 443 but can deviate if set in OCIS_URL listen 443 ssl http2; listen [::]:443 ssl http2; server_name ocis.example.com; # certificates managed by Certbot ssl_certificate /etc/letsencrypt/live/ocis.example.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/ocis.example.com/privkey.pem; # options and dhparams managed by Certbot include /etc/letsencrypt/options-ssl-nginx.conf; ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; location / { # OIDC Tokens in headers are quite large and can exceed default limits of reverse proxies proxy_buffers 4 256k; proxy_buffer_size 128k; proxy_busy_buffers_size 256k; # Disable checking of client request body size client_max_body_size 0; proxy_pass http://localhost:9200; proxy_set_header Host $host; } }
-
Add the following to the SSL definition above if SSL security should be hardened / improved:
# protocol, session timout, server cipers # NOTE: ssl cache is handled by certbot # also see: https://github.com/certbot/certbot/blob/master/certbot-nginx/certbot_nginx/_internal/tls_configs/options-ssl-nginx.conf # restrict ciphers # # IMPORTANT: depending on your setup, it is possible that certbot will also define the ciphers used. # this can lead to a nginx error about already defined ciphers. in such a case, you can comment out # the cipher definition here. ssl_ciphers "ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-SHA:ECDHE-ECDSA-AES256-SHA:ECDHE-ECDSA-AES128-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-SHA:ECDHE-RSA-AES256-SHA:ECDHE-RSA-AES128-SHA256:ECDHE-RSA-AES256-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-SHA:DHE-RSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES256-SHA256:!SHA1:!SHA256:!SHA384:!RC4:!aNULL:!eNULL:!Medium:!LOW:!3DES:!MD5:!EXP:!PSK:!SRP:!DSS:!SEED"; # use multiple curves (only if dhparams file is used) ssl_ecdh_curve secp521r1:secp384r1; # reduce time to first byte ssl_buffer_size 4k; # add strict transport security add_header Strict-Transport-Security "max-age=15768000; must-revalidate; includeSubDomains; preload;" always;
-
Check the config and reload nginx:
sudo nginx -s reload
If the server is accessible from the web, see the free SSL Labs page to check the sites SSL security.
Open a web browser, navigate to your Infinite Scale URL https://ocis.example.com
and log in as admin user with the password returned by the ocis init
command.
Apache as Reverse Proxy
Whenever a configuration change has been made, you need to do a configuration check and reload the Apache configuration. This can be done with two methods as described below. Select your preferred one. For ease of writing, the examples show sudo apache2ctl -k graceful .
|
-
sudo apache2ctl -k graceful
Note that this command includes checking and reloading the config in the same step.
-
sudo apache2ctl -t
sudo systemctl reload apache2
Note that using
systemctl reload apache2
alone will NOT validate your configuration but will execute the command in a clean environment and not in the current user environment.
Prepare Apache for certbot
-
To set up Apache as a reverse proxy with Let’s Encrypt TLS certificates, create a file called e.g.
ocis
under/etc/apache2/sites-available
with the following content:<IfModule mod_rewrite.c> <VirtualHost *:80> ServerName ocis.example.com </VirtualHost> </IfModule>
-
Activate the new Apache config and reload Apache:
sudo ln -s -f /etc/apache2/sites-available/ocis /etc/apache2/sites-enabled/ocis
sudo apache2ctl -k graceful
Issuing a Certificate via certbot for Apache
-
Run
certbot
to issue the TLS certificates:sudo certbot --apache -d ocis.example.com
Finalize the Apache Configuration
-
Adapt the config to redirect automatically to https, use the newly generated certificates and add the required proxy configuration. The full config should look like this:
<IfModule mod_rewrite.c> <VirtualHost *:80> ServerName ocis.example.com # redirect all http urls to https RewriteEngine On RewriteCond %{HTTPS} off RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI} [R=302,L,QSA] </VirtualHost> </IfModule> <IfModule mod_ssl.c> <VirtualHost *:443> ServerName ocis.example.com SSLProxyEngine on SSLProxyVerify none SSLProxyCheckPeerCN off SSLProxyCheckPeerName off SSLProxyCheckPeerExpire off ProxyPass / http://localhost:9200/ ProxyPassReverse / http://localhost:9200/ #important, otherwise 400 errors from idp ProxyPreserveHost on ## Actual values to be added by certbot # SSLCertificateFile /etc/letsencrypt/live/ocis.example.com/fullchain.pem # SSLCertificateKeyFile /etc/letsencrypt/live/ocis.example.com/privkey.pem # Include /etc/letsencrypt/options-ssl-apache.conf # SSLOpenSSLConfCmd DHParameters /etc/letsencrypt/ssl-dhparams.pem </VirtualHost> </IfModule>
-
Add the following to the SSL definition above if SSL security should be hardened / improved:
# restrict ciphers SSLCipherSUite "ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-SHA:ECDHE-ECDSA-AES256-SHA:ECDHE-ECDSA-AES128-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-SHA:ECDHE-RSA-AES256-SHA:ECDHE-RSA-AES128-SHA256:ECDHE-RSA-AES256-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-SHA:DHE-RSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES256-SHA256:!SHA1:!SHA256:!SHA384:!RC4:!aNULL:!eNULL:!Medium:!LOW:!3DES:!MD5:!EXP:!PSK:!SRP:!DSS:!SEED" # use multiple curves (only if dhparams file is used) SSLOpenSSLConfCmd Curves secp521r1:secp384r1 # add strict transport security SSLOptions +StrictRequire Header always set Strict-Transport-Security "max-age=31536000; includeSubDomains; preload" # disable ssl compression SSLCompression off
-
Reload Apache:
sudo apache2ctl -k graceful
See the linked documentation how to enable the http2 protocol for Apache.
If the server is accessible from the web, see the free SSL Labs page to check the sites SSL security.
Open a web browser, navigate to your Infinite Scale URL https://ocis.example.com
and log in as admin user with the password returned by the ocis init
command.