Binary Setup

Introduction

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

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

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.

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/bin/

    To download use:

    sudo wget -O /usr/bin/ocis <link>

    Make the binary executable with:

    sudo chmod +x /usr/bin/ocis

    Check the version installed:

    ocis version

    The output looks like this:

    ocis version 2.0.0-beta1

  • To install Infinite Scale via the package manager of your Linux system, use the package manager commands to search for ocis and install it accordingly.

    Package manager installation is in preperation and will be available soon.

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 localhost:9200 or whatever URL and port you have defined.

Start and Stop Infinite Scale

Starting Infinite Scale

Infinite Scale is started in two steps:

  • A first time start to initiate 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 basis for a default ocis.yaml file to be generated. This file you can edit 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 : /etc/ocis/ocis-config/ocis.yaml
 user       : admin
 password   : <removed for documentation>

Recurring Start of Infinite Scale

After initializing Infinite Scale for the first time, you can start the Infinite Scale runtime which includes embedded extensions. See the sections Starting Infinite Scale With Environment Variables and Configurations to Access the WebUI or Define the Infinite Scale Data Path for basic environment variables.

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 detatch it and avoid it gets stopped when closing the shell or the shell gets disconnected (SIGHUP), use the following command:

ocis server & disown -h

The same mechanism is true to start or instantinate extensions which are not started as part of the runtime like:

ocis web server & disown -h
Instantination of runtime extensions will cause errors, for more details see: Managing Extensions

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 what you want to stop, differnt commands need to be applied.

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

Stopping an extension from the runtime

Note that the ocis runtime (ocis server) needs to be active or a default error message will be returned, see Default Runtime Error Response

ocis kill [extension name]
Stopping the complete runtime with all its running extensions

Depending on the user you started ocis and with which user you are currently logged in, 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

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 ocis.service

Then copy the content of the systemd file below into the editor and save it.

  • The user ocis is just a placeholder for any user to run Infinite Scale, the user must exist or be created first.

    This user can be a system user. The following example will create a system user and group named ocis with no home directory, no login shell and no password. Depending on your OS type:

    sudo useradd --system --no-create-home --shell=/sbin/nologin ocis

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

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

    • The directory /etc/ocis/ must exist and ocis must be able to read it. For security reasons, this user should have restricted permissions. Create and set permissions, adjust the values according to your needs:

      sudo mkdir -p /etc/ocis
sudo chown -R ocis /etc/ocis
sudo chmod 0570 /etc/ocis
systemd file
[Unit]
Description=OCIS server

[Service]
Type=simple
User=ocis
Group=ocis
EnvironmentFile=/etc/ocis/ocis.env
ExecStart=ocis server
Restart=always

[Install]
WantedBy=multi-user.target

Now create the file /etc/ocis/ocis.env with the definitions of environment variables. See the following sections for additional environment variables like Configurations to Access the WebUI or Define the Infinite Scale Data Path.

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_LOG_LEVEL=error

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 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 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 e.g. a necessary 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.