Container Setup

Introduction

Images for a container-based setup of Infinite Scale are available on Docker Hub. You can easily download and start such an image with only a few commands. See the latest or stable images from Docker Hub.

This description mainly focuses on Docker which you can take as template or starting point if you are using different container managing software products.

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.

Docker Prerequisites

To fetch and run Infinite Scale in a Docker container, make sure the package docker is installed.

  • Note that when checking if software is installed on your system with the which command below, you might be shown links containing the queried names but pointing to a different program. After running a check via which, also try to execute the queried command and look if the output printed comes from docker like in the following example:

    Usage:  docker [OPTIONS] COMMAND
or
Usage:  docker compose [OPTIONS] COMMAND

  • Use the following command to check if docker is installed on your system:

    which docker

    If Docker is installed, you’ll be informed. If not, you may get no output at all or a message that it couldn’t be found. In that case you need to install Docker first.

Install Docker

  • On most Linux distributions, you can simply install Docker via the package manager. For later use, you might want to install Docker-Compose as well.

    Alternatively, install Docker depending on your OS from the Docker site. See Install Docker Engine and Install Docker Compose for details.

  • When using macOS, you have to install Docker Desktop which includes the Docker Engine, the Docker CLI client, Docker Compose, Docker Dashboard and other tools.

Check the Docker Group Membership

Running a Docker container without root privileges (sudo), requires the user to be a member of the docker group.

First, check if the docker group is already created and you are member of this group:

cat /etc/group | grep docker
docker:x:998:<your-user-name>

If the group does not exist or you are not a member, continue with Post-installation steps for Linux to create the group and add your user to it.

Image Management

Download the Infinite Scale Image

To give some terminology guidance, images are unchangeable snapshots of live containers, while containers are running (or stopped) instances of an image.

  • To download the latest Infinite Scale image, run the following command. Note that this command will download the correct image suitable for your OS if available. For Windows, Infinite Scale Docker images are not available, but might be in the future. If not explicitly declared otherwise, the latest tag is implicitely used and always reflects the current master branch. Consider using a stable release when planning ocis for production:

    docker pull owncloud/ocis

  • Check your Infinite Scale image with:

    docker images
    Example output
    REPOSITORY      TAG       IMAGE ID       CREATED       SIZE
owncloud/ocis   latest    fc4151802141   9 hours ago   98.3MB

  • Check your Infinite Scale version with the following command.

    docker inspect owncloud/ocis:latest \
   -f '{{index .Config.Labels "org.opencontainers.image.version"}}'
    Example output
    latest

Update an Image

First check the current version of the image used with the command above and compare it with the versions available on Docker Hub. When a new image is available use these steps to upgrade the image.

Read the ocis release notes before upgrading to avoid missing notes about possible breaking changes.

  • Stop the running Infinite Scale container

  • Remove the actual image

  • Download the desired new image

  • Start the Infinite Scale runtime

For detailed commands see the corresponding sections.

Remove an Infinite Scale Image

If you want to remove an Infinite Scale image, run the following command:

docker images
Example output
REPOSITORY      TAG       IMAGE ID       CREATED        SIZE
owncloud/ocis   latest    22c455afc445   46 hours ago   98.3MB

Replace <image-id> with the ID you want to remove from the above printout:

docker rmi -f <image-id>

Start the Infinite Scale Runtime

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.

Preparation

In the examples shown below, bind mounts with the following folders are used to keep data persistent and located in your home directory. Change the locations according your needs:

  • For the config we use the folder $PWD/ocis/ocis-config.

  • For data we use the folder $PWD/ocis/ocis-data.

The Infinite Scale container runs internally with the default user and group ID of 1000. To check this, type:

docker inspect owncloud/ocis -f '{{.ContainerConfig.User}}'
1000

For the folders above, the following rules apply:

  • Because bind-mounts (used in the example below) create paths if they do not exist with the root user and group, the container user cannot write into them. To overcome this issue, you have to create both folders upfront manually to avoid a permission denied problem. To do so, type:

    mkdir -p $PWD/ocis/ocis-config
    mkdir -p $PWD/ocis/ocis-data

  • The user you have logged in with must have the default user and group ID of 1000 to match the container user and group ID. If this does not match, you must take care that the container user can write into the created paths. You can do this for example with the command:

    sudo chown -Rfv 1000:1000 $PWD/ocis/

    In this case, you need to access the content of the ocis folder with root privileges or with a user matching the owner ID.

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. Note that if you do not define a host directory with a bind mount as target location, the initial setup will get lost because the container ends after executing the command. ownCloud therefore recommends either using bind mounts or Docker volumes to make the initial setup, further changes and your data persistent.

docker run --rm -it \
    --mount type=bind,source=$PWD/ocis/ocis-config,target=/etc/ocis \
    owncloud/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.yaml
 user       : admin
 password   : <removed for documentation>

If you get an error message like the following:

Could not create config: config in /etc/ocis/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

When you run the Infinite Scale container, you must specify at least the OCIS_URL as an environment variable to have browser access. This is because localhost would point to a location inside the container and not to the server being accessed. For details see: Configurations to Access the Web UI.

In the example below, replace <your-hostname> with the host name or IP address of your server.

To run the Docker container, simply type:

docker run \
    --name ocis_runtime \
    --rm \
    -it \
    -p 9200:9200 \
    --mount type=bind,source=$PWD/ocis/ocis-config,target=/etc/ocis \
    --mount type=bind,source=$PWD/ocis/ocis-data,target=/var/lib/ocis \
    -e OCIS_INSECURE=true \
    -e PROXY_HTTP_ADDR=0.0.0.0:9200 \
    -e OCIS_URL=https://<your-hostname>:9200 \
    owncloud/ocis

To access Infinite Scale, open your browser and type https://<your-hostname>:9200

While this is not used in production and for testing purposes only, you could run more than one Infinite Scale runtime container concurrently. In such a case, you have to define different ports and data paths for each of the runtime containers to avoid unexpected behavior.

Delete a Setup

If you want to delete your setup, which is both the configuration and the data, just delete the ocis-config and the ocis-data folder and restart the process described in this chapter.

Execute Infinite Scale Commands

To execute Infinite Scale commands, you have to enter the shell of the running container. To do so, list the running containers first and type the following command replacing the <container-id> accordingly:

docker exec -it <container-id> sh

You can now use commands like ocis --help or others to manage your runtime services.

To exit the container’s shell, either type exit or CTRL+D.

Useful Docker Parameters

The following Docker command-line options are quite helpful to know:

--env, -e: Set environment variables

Use this to pass only a few environment variables to the run command.

--interactive, -i: Keep STDIN open even if not attached

This keeps STDIN open to the container.

--tty, -t: Allocate a pseudo-TTY

Allocate a virtual terminal session within the container.

--publish, -p: Publish a container’s port(s) to the host

Defines the port mapping <hostPort>:<containerPort>. Use the port mapping if you want to access the dockerized Infinite Scale web user interface.

--rm: Automatically remove the container when it exits

Tell the Docker daemon to clean up the container and remove the file system after the container exits.

--env-file: Read in a file of environment variables

If you have more environment variables to hand over, put them all in a file and use this command-line option. Preferably use /etc/ocis on your host as location. See Configuration Rules for more details.

--name: Assign a name to the container

By default, containers created with docker run are given a random name like small_roentgen which may not be suitable to identify their purpose properly. Giving containers a meaningful name helps to identify them more easily.

--restart: Restart policy to apply when a container exits

See the details in the docker run documentation for available options. Consider always as a good starting point.

--mount: Attach a filesystem mount to the container

  • Docker volumes (--type=volume) are completely managed by Docker and have no server OS dependency. See Create a service which creates an NFS volume for an example.

    • Note the volume mount target path target=/var/lib/ocis which uses the default Infinite Scale data path if not otherwise defined.

    • Note that the directory on the host must already exist, it will not be created by docker.

    • Note the use of $PWD/ocis/…​ for the paths when using the users home directory. When using ~/ocis/…​, you will get an error like mount path must be absolute.

  • Bind mounts (--type=bind) depend on the directory structure and OS of your server. Use this type to mount a local directory of your OS. Example: -v /some/host/dir:/var/lib/ocis, which uses the default Infinite Scale data path if not otherwise defined. You should always create the source directories upfront because of correct permissions (see: Preparation), despite the fact that bind-mounts create directories that do not yet exist on the host. In such a case, the directory will be created automatically using the user the docker service runs with, usually the root user, making the source path inaccessible to the user inside the docker container.

    macOS cannot use bind mounts, as Docker Desktop for macOS does currently not fully support extended attributes. Use a Docker volume for persistent data instead.
In general, a filesystem at your OS mount point must be a supported filesystem which supports extended attributes.

Useful Docker Commands

Start the Container Detached

Note that the docker run command will bind the container to the shell you are using. If you want to detach it so it won’t be stopped when the shell is closed or gets disconnected (SIGHUP), use the following docker run command-line option:

-d, --detach: Run container in background and print container ID

The Docker container runs in the background of your terminal. It does not receive input or display output.

List Running Containers

To list all running containers, type:

docker ps
Example output
CONTAINER ID   IMAGE           COMMAND                  CREATED         STATUS         PORTS                                       NAMES
a0e4db3e91e8   owncloud/ocis   "/usr/local/bin/ocis server"   8 seconds ago   Up 6 seconds   0.0.0.0:9200->9200/tcp, :::9200->9200/tcp   ocis_runtime

Stop a Running Container

To stop a running detached container, you need the container ID which you will get with the above command. Then type the following command and replace <container-id> with the ID of the container you want to stop:

docker stop <container-id>

Restarting a Container

Restarting a Docker container does an equivalent of docker stop and docker start. Note that the same parameters are used as before when the container has been started with the run command. To restart a container, type the following and replace the <container-id> accordingly:

docker restart <container-id>

Autostart Infinite Scale Runtime on Boot

To autostart Infinite Scale when the server boots or reboots, some steps need to be performed.

Autostart the Docker Service

Check if the Docker service is set to be automatically started on boot:

sudo systemctl is-enabled docker

  • If the output is enabled, you can proceed with the section to autostart the container.

  • If the output is disabled, follow the next steps to enable it:

    sudo systemctl enable --now docker

    This will create an output like:

    Created symlink /etc/systemd/system/multi-user.target.wants/docker.service → /lib/systemd/system/docker.service.

    Then check if the service has started with:

    sudo systemctl status docker

    This should display output like:

    ● docker.service - Docker Application Container Engine
     Loaded: loaded (/lib/systemd/system/docker.service; enabled; vendor preset: enabled)
     ...

Dependent Docker Service Startup

If you are using bind mounts and want to ensure that you have e.g. a necessary NFS mount point up and running before the Docker service and the container starts up, see Start a Service After a Resource is Mounted.

This step can be an important measure, because if the container starts up but the necessary mount point is not available, you may be in an undefined Infinite Scale operating state.

Autostart the Container

To start the container automatically after the Docker service has started or when the container exits because of an error, add the --restart=always command line option to the docker run command. You can replace always with other options suitable for your environment. If you do not want the container to autostart any longer, you have to stop it manually first.

The docker logs command shows information logged by a running container, which is useful if you have detached it. To show the logs and follow log output, type the following and replace the <container-id> accordingly:

docker logs -f <container-id>

Multi-Container Environment

Containers run in isolation and don’t know anything about other processes or containers on the same machine. If containers are on the same network, they can talk to each other. See the Multi Container Apps documentation to read more about this topic.

In a nutshell, you have to create a Docker network and reference this network in all the containers that should be able to talk to each other.

GUI for Docker

Docker provides a GUI named Docker Desktop for various operating systems, though you can use other tools like Portainer.