The ocis init Command

Introduction

When setting up Infinite Scale, the ocis init command can be used for basic configuration but is not suitable for all environments. This document describes the details.

Deployments

In general, the ocis init command initializes ocis for the first run and creates an ocis.yaml configuration file. See Configuration Rules for the file location. This command is helpful if you do not provide the necessary settings manually, but some rules apply.

Binary Deployment

When using the a binary deployment like described in the Minimal Bare Metal Deployment, the command is recommended to be run manually once before first usage, though you can also fully configure the initial setup manually.

  • The following command line parameters or their equivalent environment variables can be defined to configure the ocis init command. When using environment variables the following structure is used; multiple variables are allowed:

    <variable1>=<value1> \
<variable2>=<value2> \
... \
ocis init

  • --admin-password or --ap
    ADMIN_PASSWORD or IDM_ADMIN_PASSWORD, value=password

    When running ocis init, a random admin password will be printed to the shell for first login. Though the password can be changed afterwards in the UI, it is possible to define it right from the start when initializing.

  • --insecure
    OCIS_INSECURE, value=true|false

    This allows to use transport security, but disables certificate verification. Useful with self-signed certificates to avoid certificate warnings. If set, the value will also be written to the config file. In such a case, when calling ocis server, it is not necessary to set the environment variable again with each start.

  • --config-path
    OCIS_CONFIG_DIR, value=absolute_path

    Manually set the config directory to deviate from the default.

    If using this setting, the environment variable MUST be used when starting ocis server.

  • --force-overwrite or -f
    OCIS_FORCE_CONFIG_OVERWRITE, value=true|false

    If you already have run ocis init and a config has been defined, a consecutive run will cause a warning that a config already exists. Use this if you want to create a new configuration.

    When setting this environment variable, the existing configuration will get overwritten and the existing installation and its data is no longer accessible. The use is intended for development purposes only.

Container Setup

When deploying via docker run as described in Container Setup, initialisation needs to be triggered once before the first full start. See the referenced page how to do so.

Container Orchestration

Docker Compose

When deploying via docker compose as described in Container Orchestration, you will find in the examples provided the following command:

command: ["-c", "ocis init || true; ocis server"]

When executed, this command will run ocis init, but skips initialisation if there is a configuration found. In case it is not found, ocis.yaml will be created and any output of the initialisation will get logged.

Kubernetes

When deploying via Kuberentes and Helm Charts as described in Container Orchestration you can run the ocis init command once to get the minimum configuration parameters, but any configuration must be handed over either via environment variables and/or via the Helm Chart / yaml files! Use the provided Helm Charts as your configuration base and adjust as needed.

Command Notes

Whenever there is a change in the existing configuration, independent of whether ocis init was run before, ocis init will:

  • fail if it finds an existing ocis.yaml file.

  • not update any existing configuration.

  • overwrite an existing configuration when using the --force-overwrite command option - which is intended for development purposes only. For a brief overview see the ocis init description in the General Information documentation.

How to Apply Manual Changes

If changes are necessary after running ocis init, these changes can be applied in different ways:

  • Adding changes in ocis.yaml.

  • Providing changes via environment variables.

  • Providing changes via yaml files.

In any case, after changes have been applied, Infinite Scale bust be restarted to make changes effective.

Diff Mode

ocis init provides an a additional argument with which you can generate a patchable diff file. The --diff argument can be used when you update to a new Infinite Scale version and want to see which changes to mandatory settings have appeared. Using the diff argument is safe, as the command never changes any settings.

The diff is stored in the config folder as ocis.config.patch file and can either be applied to ocis.yaml using the linux patch command or you can apply the changes manually.

Example diff command
ocis init --diff
Example diff file when upgrading from 5 (production) to 6 (rolling)
--- /home/user_1/.ocis/config/ocis.yaml        2024-08-02 12:31:45.892704129 +0200
+++ /home/user_1/.ocis/config/ocis.yaml.tmp    2024-08-02 12:34:07.881151244 +0200
@@ -27,6 +27,11 @@
     idm_password: W&U!5HMYKe^Kjb@bZQ9hK1+IQ*3C.eZ0
     reva_password: .5RpDorc*5L$kox#J-0PL@h^H+6V=Ezv
     idp_password: eGP$Of5C7$#%^ikG6K8p%LO9arNRnHEA
+collaboration:
+  wopi:
+    secret: ""
+  app:
+    insecure: true
 proxy:
   oidc:
     insecure: true
@@ -116,3 +121,7 @@
   service_account:
     service_account_id: 433d9b85-6a54-4ef0-87ff-b1c419eedcb8
     service_account_secret: 9&SO@a$t%G7wHup^QtQ^qXDqfDzo7TM&
+activitylog:
+  service_account:
+    service_account_id: 433d9b85-6a54-4ef0-87ff-b1c419eedcb8
+    service_account_secret: 9&SO@a$t%G7wHup^QtQ^qXDqfDzo7TM&