Discover oCIS with Docker

Prerequisites

Local docker installation (e.g. Docker for Desktop)
Check oCIS and Containers

Start oCIS with docker compose

Create the project

Use the following skeleton as a docker-compose.yml:

mkdir simple-ocis && \
cd simple-ocis && \
touch docker-compose.yml

Copy the following file content into docker-compose.yml and save it.

version: "3.7"

services:
  ocis:
    image: owncloud/ocis:latest
    environment:
      # INSECURE: needed if oCIS / Traefik is using self generated certificates
      OCIS_INSECURE: "true"

      # OCIS_URL: the external domain / ip address of oCIS (with protocol, must always be https)
      OCIS_URL: "https://localhost:9200"

      # OCIS_LOG_LEVEL: error / info / ... / debug
      OCIS_LOG_LEVEL: info

Initialize

Run ocis init to create a config

docker run --rm -it -v $(pwd):/etc/ocis/ owncloud/ocis:latest init

You will get the following output:

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

=========================================
 generated OCIS Config
=========================================
 configpath : /etc/ocis/ocis.yaml
 user       : admin
 password   : t3p4N0jJ47LbhpQ04s9W%u1$d2uE3Y.3

Check your local folder. We just generated a default ocis configuration file with random passwords and secrets.

ls # list the current folder
docker-compose.yml                    ocis.yaml # ocis.yaml has been generated

Run cat ocis.yaml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54


token_manager:
  jwt_secret: X35rffWpS9BR.=^#LDt&z3ykYOd7h@w*
machine_auth_api_key: -0$4ieu5+t6HD6Ui^0PpKU6B0qxisv.m
system_user_api_key: oVxICwMR9YcKXTau+@pqKZ0EO-OHz8sF
transfer_secret: e%3Sda=WFBuy&ztBUmriAbBR$i2CmaDv
system_user_id: b7d976a1-7300-4db7-82df-13502d6b5e18
admin_user_id: c59a6ae9-5f5e-4eef-b82e-0e5c34f93e52
graph:
  spaces:
    insecure: false
  identity:
    ldap:
      bind_password: wElKpGjeH0d.E4moXh=.dc@s2CtB0vy%
idp:
  ldap:
    bind_password: Ft2$2%#=6Mi22@.YPkhh-c6Kj=3xBZAb
idm:
  service_user_passwords:
    admin_password: t3p4N0jJ47LbhpQ04s9W%u1$d2uE3Y.3
    idm_password: wElKpGjeH0d.E4moXh=.dc@s2CtB0vy%
    reva_password: pJAdZ2fU!SFKgcdDPRW%ruIiNM6GnN1D
    idp_password: Ft2$2%#=6Mi22@.YPkhh-c6Kj=3xBZAb
proxy:
  insecure_backends: false
frontend:
  archiver:
    insecure: false
auth_basic:
  auth_providers:
    ldap:
      bind_password: pJAdZ2fU!SFKgcdDPRW%ruIiNM6GnN1D
auth_bearer:
  auth_providers:
    oidc:
      insecure: false
users:
  drivers:
    ldap:
      bind_password: pJAdZ2fU!SFKgcdDPRW%ruIiNM6GnN1D
groups:
  drivers:
    ldap:
      bind_password: pJAdZ2fU!SFKgcdDPRW%ruIiNM6GnN1D
storage_system:
  data_provider_insecure: false
storage_users:
  data_provider_insecure: false
ocdav:
  insecure: false
thumbnails:
  thumbnail:
    transfer_secret: z-E%G8MTeFpuT-ez2o8BjfnG1Jl2yLLm
    webdav_allow_insecure: false
    cs3_allow_insecure: false

Password initialisation
During the run of ./ocis init, the password for the admin user has been set to a random string.

You can override that later by setting IDM_ADMIN_PASSWORD=secret. The ENV variable setting always overrides the config file.

Mount the config file

Add the config file as a bind mount.

    volumes:
      # mount the ocis config file inside the container
      - "./ocis.yaml:/etc/ocis/ocis.yaml"

Apply the changes

docker compose up -d

The service should be running.

docker compose ps
NAME                 COMMAND                  SERVICE             STATUS              PORTS
simple-ocis-ocis-1   "/usr/bin/ocis server"   ocis                running             9200/tcp

Open the port 9200 to the outside

ports:
  - 9200:9200

Add a port mapping to your docker compose file and run docker compose up -d again. You should now be able to access https://localhost:9200 and log in. You will get a warning from your browser that the connection is not safe because we are using a self-signed certificate. Accept this warning message to continue. Use the user admin and the password which has been initialized before.

Congratulations! You have successfully set up a simple Infinite Scale locally.

docker compose up
You do not need to shut down your service to apply changes from the docker-compose.yml file. Running docker compose up -d again is enough. Docker compose always tries to bring all services to the desired state.

docker compose ps
This gives you a status of the services of the project.

docker compose exec <service name> <command>
This command is handy to run specific commands inside your service. Try docker compose exec ocis ocis version.

Persist data, restart and logging

The key to a successful container setup is the persistence of the application data to make the data survive a re-boot. Docker normally uses volumes for this purpose. A volume can either be a “named volume” which are completely managed by docker and have many advantages (see the linked docker documentation), or “bind mounts” which are using the directory structure and OS of the host system. In our example we already use a bind mount for the config file. We will now add a named volume for the oCIS data directory.

This is the way we should configure the ocis service:

    volumes:
      # mount the ocis config file inside the container
      - "./ocis.yaml:/etc/ocis/ocis.yaml"
      # short syntax for using a named volume
      # in the form <volume name>:<mount path in the container>
      # use a named volume for the ocis data directory
      - "ocis-data:/var/lib/ocis"
      # or the more verbose syntax
      #- type: volume
      #  source: ocis-data # name of the volume
      #  target: /var/lib/ocis # the mount path inside the container

The docker-compose.yml needs to declare the named volumes globally, add this at the bottom of the file:

# https://docs.docker.com/compose/compose-file/compose-file-v3/#volumes
# this declares the named volume with all default settings
# you can also see the volume when running `docker volume list`
volumes:
  ocis-data:

Now let us configure the restart policy and the logging settings for the ocis service:

    # https://docs.docker.com/compose/compose-file/compose-file-v3/#restart
    restart: always # or on-failure / unless-stopped

    # https://docs.docker.com/config/containers/logging/configure/
    # https://docs.docker.com/compose/compose-file/compose-file-v3/#logging
    # the default log driver does no log rotation
    # you can switch to the "local" log driver which does rotation by default
    logging:
      driver: local
    # otherwise you could specify log rotation explicitly
    #  driver: "json-file" # this is the default driver
    #  options:
    #    max-size: "200k" # limit the size of the log file
    #    max-file: "10" # limit the count of the log files

Apply your changes! Just run docker compose up -d again.

Now you have an oCIS which will survive reboots, restart automatically and has log rotation by default.

Access the logs via docker compose logs -f and do some actions in the frontend to see the effect. Create data by uploading files and adding more users. Then run docker compose down to shut oCIS down. Start it again docker compose up -d, log in again and check that your data has survived the reboot.

Pin the oCIS version

Last but not least, it is never a good idea to use the latest docker tag. Pin your container image to a released version.

    image: owncloud/ocis:latest@sha256:5ce3d5f9da017d6760934448eb207fbaab9ceaf0171b4122e791e292f7c86c97
    # the latest tag is not recommended, because you don't know which version you'll get
    # but even if you use `owncloud/ocis:1.16.0` you cannot be sure that you'll get
    # the exact same image if you pull it at a later point in time (because docker image tags are not immutable).
    # To be 100% that you always get the same image, you can pin the digest (hash) of the
    # image. If you do a `docker pull owncloud/ocis:latest`, it also will also show you the digest.
    # see also https://docs.docker.com/engine/reference/commandline/images/#list-image-digests

Wrapping up

If you have completed this guide, your docker-compose.yml should look like the following example:

Solution ...

version: "3.7"

services:
  ocis:
    image: owncloud/ocis:latest@sha256:5ce3d5f9da017d6760934448eb207fbaab9ceaf0171b4122e791e292f7c86c97
    # the latest tag is not recommended, because you don't know which version you'll get
    # but even if you use `owncloud/ocis:1.16.0` you cannot be sure that you'll get
    # the exact same image if you pull it at a later point in time (because docker image tags are not immutable).
    # To be 100% that you always get the same image, you can pin the digest (hash) of the
    # image. If you do a `docker pull owncloud/ocis:latest`, it also will also show you the digest.
    # see also https://docs.docker.com/engine/reference/commandline/images/#list-image-digests
    environment:
      # INSECURE: needed if oCIS / Traefik is using self generated certificates
      OCIS_INSECURE: "true"

      # OCIS_URL: the external domain / ip address of oCIS (with protocol, must always be https)
      OCIS_URL: "https://localhost:9200"

      # OCIS_LOG_LEVEL: error / info / ... / debug
      OCIS_LOG_LEVEL: info
    volumes:
      # mount the ocis config file inside the container
      - "./ocis.yaml:/etc/ocis/ocis.yaml"
      # short syntax for using a named volume
      # in the form <volume name>:<mount path in the container>
      # use a named volume for the ocis data directory
      - "ocis-data:/var/lib/ocis"
      # or the more verbose syntax
      #- type: volume
      #  source: ocis-data # name of the volume
      #  target: /var/lib/ocis # the mount path inside the container
    ports:
      - 9200:9200
    # https://docs.docker.com/compose/compose-file/compose-file-v3/#restart
    restart: always # or on-failure / unless-stopped

    # https://docs.docker.com/config/containers/logging/configure/
    # https://docs.docker.com/compose/compose-file/compose-file-v3/#logging
    # the default log driver does no log rotation
    # you can switch to the "local" log driver which does rotation by default
    logging:
      driver: local
    # otherwise you could specify log rotation explicitly
    #  driver: "json-file" # this is the default driver
    #  options:
    #    max-size: "200k" # limit the size of the log file
    #    max-file: "10" # limit the count of the log files

# https://docs.docker.com/compose/compose-file/compose-file-v3/#volumes
# this declares the named volume with all default settings
# you can also see the volume when running `docker volume list`
volumes:
  ocis-data: