General Info

Introduction

This document covers general aspects of Infinite Scale like start modes, extensions, important minimum configuration etc. for a common understanding.

The example commands shown need to be adjusted depending on whether you are using the Binary Setup or a Container Setup.

When using global options on startup, you can always use command line options or environment variables. Run ocis help and see Starting Infinite Scale With Environment Variables for details.

Embedded Supervisor (Runtime)

Infinite Scale has an embedded supervisor for managing the runtime und reducing the memory footprint. In addition, this supervisor takes care that an extension will be restarted automatically if it fails. When using an external supervisor like systemd, Kubernetes or others, the embedded supervisor is not needed.

Deciding the Startup Mode

The following two mode types do not predefine a particular installation method like the manual or container setup. When using Kubernetes, the embedded supervisor is not necessary, the supervisor of the underlying system is used.

Starting Infinite Scale using the embedded supervisor

This mode can be used when scaling is not the primary focus and can be the case if you have a:

when you do testing and/or development
small productive environment (Single Server Setup) or

Starting Infinite Scale in unsupervised mode

This mode is used when availability, scaling and the adjustment to dynamically changing requirements have a high priority. In this case, an external supervisor like Kubernetes is used to deploy and run Infinite Scale with its extensions.

Start Infinite Scale With All Predefined Extensions

When you type ocis server, the embedded supervisor is automatically used and starts available predefined extensions automatically. The supervisor starts by default on port 9250 and listens for commands regarding the lifecycle of the supervised extensions.

To list the started predefined extensions, type:

ocis list

This will print an output like:

+--------------------+
|     EXTENSION      |
+--------------------+
| app-provider       |
| app-registry       |
| auth-basic         |
| auth-bearer        |
| auth-machine       |
| frontend           |
| gateway            |
| graph              |
| graph-explorer     |
| groups             |
| idm                |
| idp                |
| nats               |
| notifications      |
| ocdav              |
| ocs                |
| proxy              |
| search             |
| settings           |
| sharing            |
| storage-publiclink |
| storage-shares     |
| storage-system     |
| storage-users      |
| store              |
| thumbnails         |
| users              |
| web                |
| webdav             |
+--------------------+

Managing Extensions

Extensions are microservices which can be started, stopped or instantiated. An Extension Rules documentation as been added to explain some background. Please read this carefully to avoid unwanted behavior. For details of each extension see the Extensions documentation.

List Available Extensions

Just type ocis to get a list of commands and available extensions.

When typing ocis <extension-name> --help, you will get detailed help regarding the specified extension.

Manage Instances of Extensions

Infinite Scale Supervised Extensions

You can start all available extensions in supervised mode with the command below. Note that the extensions started with the runtime share the same PID.

Start the Infinite Scale Runtime

ocis server

List running extensions

ocis list

Unsupervised Extensions

At any time, you can create unsupervised instances of an extension with ocis [extension-name] server, for example ocis proxy server. These extensions are independent of extensions in supervised mode and have their own PID. The Instances are managed with classic OS methods or e.g. via Kubernetes.

Note that you need configuration for and access to the extension instances like with a load balancer when you scale.

Configuring Extensions

To configure extensions, see the section Extensions in the Deployment documentation.

Configuration Rules

Administrators must be aware of the sources, the location and order applied (the configuration file arithmetics). Mismanaging them can be a source of confusion leading to undesired results on the final configuration created and applied.

Infinite Scale uses a hierarchical structure for its configuration, where each element overwrites its precedent. These are:
1. Environment variables
2. Extension configuration file
3. Infinite Scale configuration file

The default locations for config files are:

For container images (inside the container)
/etc/ocis/

For binary releases
$HOME/.ocis/config/

You can deviate from the default location and define a custom configuration file location on startup using the environment variable OCIS_CONFIG_FILE.

When using a system user for the runtime which has no login and therefore no home directory like when used Setting up systemd for Infinite Scale, you must specify a configuration file location.

Configuration File Naming

The configuration files for Infinite Scale are YAML-based (a human-friendly data serialization language).

The filename to define a config has the following namespace:

ocis.yaml
 or
[extension name].yaml

You can list the possible extension names by typing:

ocis list

Starting Infinite Scale With Environment Variables

You can use environment variables to define or overwrite config parameters which will be used when starting Infinite Scale like:

PROXY_HTTP_ADDR=localhost:5555 ocis server

or when using multiple environment variables like:

PROXY_HTTP_ADDR=localhost:5555 \
PROXY_DEBUG_ADDR=localhost:6666 \
ocis server

Remember the note in Infinite Scale Supervised Extensions when killing/restarting extensions in supervised mode.

Globally Shared Logging Values

When running in supervised mode (ocis server), it is beneficial to have common values for logging so that the log output is correctly formatted or everything is piped to the same file without duplicating config keys and values all over the place. This is possible using the global log config key with the following example:

ocis.yaml

log:
  level: error
  color: true
  pretty: true
  file: /var/tmp/ocis_output.log

In case of an extension overwriting its shared logging config received from the main ocis.yaml file, you must specify all values.

Log Config Keys

These are the necessary log keys and the available values:

log:
  level: [ error | warning | info | debug ]
  color: [ true | false ]
  pretty: [ true | false ]
  file: [ path/to/log/file ] # MUST not be used with pretty = true

Configurations to Access the WebUI

You can easily access Infinite Scale via ownCloud Web with minimal configuration needs. Without going into too much detail, you need to provide the following two environment variables. See also the section about Handling Certificates and Demo Users and Groups.

OCIS_URL

Expects a URL including protocol, host and optionally port to simplify configuring all the different services. Other extension environment variables also using an URL still take precedence if set, but will fall back to this URL if not set.

If you need to access Infinite Scale running on a VM or a remote machine via a host name other than localhost or in a container, you need to configure the host name with OCIS_URL. The same applies if you are not using host names but an IP address (e.g. 192.168.178.25) instead.

PROXY_HTTP_ADDR

When using 0.0.0.0:9200, the proxy will listen to all available interfaces. If you want or need to change that based on your requirements, you can use a different address e.g. to bind the proxy to an interface.

Handling Certificates

Certificates are necessary to secure browser access. Infinite Scale can run with embedded self-signed certificates mainly used for testing purposes or signed certificates provided by the admin. To tell Infinite Scale which kind of certificates you are using, the environment variable OCIS_INSECURE is used.

Embedded Self-Signed Certificates

In order to run Infinite Scale with automatically generated and self-signed certificates, set OCIS_INSECURE=true.

OCIS_INSECURE=true \
PROXY_HTTP_ADDR=0.0.0.0:9200 \
OCIS_URL=https://localhost:9200 \
ocis server

Provided Signed Certificates

Self-Signed Certificates

In case your certificates are self-signed, set OCIS_INSECURE=true like in the example of embedded self-signed certificates above.

Certificates Signed by a Trusted CA

If you have your own certificates already in place, make Infinite Scale use them by adding the following environment variables to the command. Replace the certificates path and file names according to your needs:

OCIS_INSECURE=false \
PROXY_HTTP_ADDR=0.0.0.0:9200 \
OCIS_URL=https://localhost:9200 \
PROXY_TRANSPORT_TLS_KEY=./certs/your-host.key \
PROXY_TRANSPORT_TLS_CERT=./certs/your-host.crt \
ocis server

Define the Infinite Scale Data Path

Because Infinite Scale does not use a database for storing information like users, groups, spaces, internal data, etc., it saves all this data to a permanent file location. This location is also used for storing user-generated data and must be a supported filesystem as described in Filesystems and Shared Storage.

The environment variable used to define this path is OCIS_BASE_DATA_PATH.

The following rules apply:

If you do NOT define this environment variable, the following applies:
- The base path is by default $HOME/.ocis/ after performing a manual setup.
- The base path is by default /var/lib/ocis inside the container when using the container setup.
The directory must exist and the user used for Infinite Scale must have full access and permissions.

You must set this environment variable to a valid path when using the manual installation having a system user for Infinite Scale, because a system user has no logon and therefore no home directory!

The location must exclusively be used by Infinite Scale. Writing into this location not using Infinite Scale is strictly discouraged to avoid any unexpected behaviour.

Default Users and Groups

Default users and groups are only created when you initialize Infinite Scale as first task. The same is true for demo users and groups which need an environment variable to be set on initializing Infinite Scale to get created.

If you have not declared demo user creation during initializing, you can for the time being only empty the Infinite Scale base directory and remove the ocis.yaml file which resets the system. Then you can start from scratch and enable demo user creation.

Admin User

An admin user will be created when running the ocis init command with the following credentials:

Admin user and group created on first ocis start
Username	Password	Email	Role	Group
admin	Printed by the output of `ocis init`	admin@example.org	admin	users

Login to the webinterface with this admin user and change relevant data according your needs or create new users. As an example to reach out the webinterface use https://localhost:9200.

Demo Users and Groups

Create Demo Users and Groups

You can let Infinite Scale create demo users and groups for testing purposes. Because these demo users and groups can be a significant security issue, you should remove them before going productive or your system is exposed to the outside world, for details see Securing Infinite Scale.

To let Infinite Scale create these demo users and groups for you, start the runtime the very first time with:

IDM_CREATE_DEMO_USERS=true \
ocis server

List of available demo users and groups
Username	Password	Email	Role	Groups
einstein	relativity	einstein@example.org	user	users, philosophy-haters, physics-lovers, sailing-lovers, violin-haters
marie	radioactivity	marie@example.org	user	users, physics-lovers, polonium-lovers, radium-lovers
moss	vista	moss@example.org	admin	users
richard	superfluidity	richard@example.org	user	users, philosophy-haters, physics-lovers, quantum-lovers
katherine	gemini	katherine@example.org	space admin	users, sailing-lovers, physics-lovers, quantum-lovers

You can now login with one of the demo users created using the OCIS_URL in you browser like https://localhost:9200.

Manage Users and Groups

If you have enabled demo users and groups and you want to manage or delete them, use the web UI, e.g. https://localhost:9200.

Using a Reverse Proxy

When using a reverse proxy like Traefik and the reverse proxy manages the certificates to secure the access, there is no need to use certificates between the reverse proxy and Infinite Scale again. You can therefore set OCIS_INSECURE=false or remove it completely.