Binary Setup

Introduction

This description gives a brief overview and can be used as basic template running the ocis binary, including an example of how to configure systemd. It does not cover extended deployment tasks

Installing the Infinite Scale binary manually works well if you want to quickly test Infinite Scale without performing additional tasks like a container preparation, Kubernetes deployment or using a reverse proxy. Of course you can use it for production in your environment, too. See the Availability and Scalability documentation for impacts.

Infinite Scale can either be downloaded from ownCloud or installed via the package manager of your Linux system. Packages will be available soon. Use the way you prefer, but keep in mind that the download version is updated more frequently than the package manager version.

ownCloud highly recommends reading the General Info as it contains valuable information about configuration rules, managing services and default paths - just to mention some of the useful topics.

Prerequisite

Infinite Scale by default relies on Multicast DNS (mDNS), usually via avahi-daemon. If your system has a firewall, make sure mDNS is allowed in your active zone and http and https ports are open.

Installation

  • 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. Check the sort order on the modification date to get the most recent releases on top. Depending on your system and preferences, you may want to save the binary in /usr/local/bin.

    To download use:

    sudo wget -O /usr/local/bin/ocis <file_url>

    Make the binary executable with:

    sudo chmod +x /usr/local/bin/ocis

    Check the version installed:

    ocis version

    The output looks like this:

    Version: 5.0.9
Compiled: 2024-10-24 00:00:00 +0000 UTC

No running services found.

Getting Command Line Help

To get a list of available options and commands type:

ocis

or

ocis --help

Accessing the Infinite Scale Runtime

When you have configured and started the Infinite Scale runtime either manually or via systemd as described below, you can access it via a browser using https://localhost:9200.

If you want to reuse an already configured minimized setup for any other address than https://localhost, you must use a reverse proxy. When Infinite Scale is accessed, it forwards requests to the embedded IDP service which requires a secure connection. See the Bare Metal Deployment with systemd for more details on using a reverse proxy setup.

Start and Stop Infinite Scale

Starting Infinite Scale

Infinite Scale is started in two steps:

  • A first time start to initialize the system and

  • a recurring start after initialization.

Refer to the Default Users and Groups section if you want to have demo users created when initializing the system.

First Time Start

Infinite Scale needs a first time initialization to set up the environment. You will need to answer questions as the basis for generating a default ocis.yaml file. You can edit this file later. The default location for config files is, if not otherwise defined, $HOME/.ocis/config/. For details see: Configuration Rules. Type the following command to initialize Infinite Scale.

ocis init

On success, you will see a message like:

Do you want to configure Infinite Scale with certificate checking disabled?
 This is not recommended for public instances! [yes | no = default]

=========================================
 generated OCIS Config
=========================================
 configpath : <your-user>/.ocis/config/ocis.yaml
 user       : admin
 password   : <removed for documentation>

If you get an error message like the following:

Could not create config: config in ~/.ocis/config/ocis.yaml already exists

you already have created a configuration once. As you cannot overwrite the existing configuration, you must delete the old configuration first to proceed. For more details, see: Initialize Infinite Scale.

Recurring Start of Infinite Scale

After initializing Infinite Scale for the first time, you can start the Infinite Scale runtime which includes embedded services. See the sections Starting Infinite Scale With Environment Variables and Configurations to Access the Web UI or Base Data Directory for basic environment variables.

You cannot instantiate runtime services though you can define which services should start or be excluded from starting. See Managing Services for more details.

The example commands shown below have no environment variables or command line options for ease of reading, add them according your needs.

To start the Infinite Scale runtime type:

ocis server

Note that this will bind ocis to the shell you are running. If you want to detach it and avoid it being stopped when closing the shell or the shell gets disconnected (SIGHUP), use the following command:

Bash
ocis server & disown -h
ZSH
ocis server & disown %%

See the respective shell documentation for how to manage processes respectively detach and re-attach sessions.

List Running Infinite Scale Processes

To list all running ocis processes type:

ps ax | grep ocis | grep -v grep
 221297 pts/1    Sl     0:04 ocis server
 221706 pts/0    Sl     0:00 ocis proxy

Stopping Infinite Scale

Depending on what you want to stop, different commands need to be applied.

If a service is being terminated with its PID, the signal SIGTERM (-15) is used. Note that SIGTERM politely asks a process to terminate. It will terminate gracefully, cleaning up all resources (files, sockets, child processes, etc.), deleting temporary files and so on.

Stopping the complete runtime with all its running services

Depending on the user you started ocis with and which user you are currently logged in as, you may need to use sudo for proper permissions.

ps ax | grep "ocis server" | grep -v grep | \
   awk '{ print $1 }' | xargs kill -15
Stopping a particular ocis PID

First identify which PID you want to terminate:

ps ax | grep "ocis" | grep -v grep

This may give an output like the following:

 221297 pts/1    Sl     0:04 ocis server
 221706 pts/0    Sl     0:00 ocis proxy

To terminate the ocis proxy service type the following command, where sudo may not be necessary depending on the permissions of the logged-in user. Replace the PID according the output from above:

sudo kill -15 221706

Setting up systemd for Infinite Scale

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

  • We strongly advise against using the user root for this purpose.

  • Since the ocis user doesn’t have a home directory, the directories /etc/ocis and /var/lib/ocis must exist and the user ocis must be able to read it.

    sudo mkdir -p /etc/ocis /var/lib/ocis
    sudo chown -R ocis:ocis /etc/ocis /var/lib/ocis

  • Placing the environment file in /etc/ocis is only a suggestion, but a good one.

    • Create the file /etc/ocis/ocis.env with the definitions of environment variables. See the following sections for information on additional environment variables: Configurations to Access the Web UI and Base Data Directory.

      This is just an example with a minimal set of environment variables used. 
      OCIS_INSECURE=true
OCIS_URL=https://localhost:9200
PROXY_HTTP_ADDR=0.0.0.0:9200
OCIS_CONFIG_DIR=/etc/ocis
OCIS_BASE_DATA_PATH=/var/lib/ocis
OCIS_LOG_LEVEL=error

Use the following command to initialize the ocis config:

OCIS_CONFIG_DIR=/etc/ocis sudo -u ocis ocis init --insecure true

Setup 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. ocis_bin

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.