{{sidenavigation.sidenavigationExpandLabel}}
{{getMsg('Help_YouAreHere')}}: {{page.title}} {{page.title}}
{{$root.getMsg("downLoadHelpAsPdf")}} {{helpModel.downloadHelpPdfDataStatus}}

Docker Container Setup

i-net CoWork can be used from inside a Docker Container. There is a pre-built container based up on an alpine release at Docker Hub. The container only brings the application and tools required to run the application.

Note: The container does not provide any default users. You have to use the Sign Up button to create a new user account first. After running the docker command, open the server UI, e.g. http://localhost:7000. You can find the Sign Up button at the top right of the server UI. See below for advanced use cases.

Quickstart

Run the following command to start an i-net CoWork Docker Container:

docker run -d -p 7000:7000 --name cowork inetsoftware/i-net-cowork

Available Tags

  • i-net CoWork 24.x: latest, alpine-24 (latest can be the next major version, new license key may be required)
  • i-net CoWork 23.x: alpine-23
  • i-net CoWork 22.x: alpine-22

Creating a pre-set configuration

The i-net CoWork Docker Container should be pre-configured using either a configuration properties file or environment variables. Either way, a local installation with the specific setup should be created first. Using the Maintenance module a backup of the configuration can be created and the configuration properties file in there can be used as a basis.

Note: To have the container fully set up on startup you have to specify at least the following properties: CONF_listener__port and CONF_licensekey

Note: In private cloud environments you have to set the property CONF_serverURL as well. It is recommended to set this property in other environments too.

Adding the configuration

A configuration file can be added by using a volume or any other means that adds a specified configuration to the container. The default configuration file can be used or a different one can be set using an environment variable. See Environment Properties Matrix.

Setting up the configuration using environment variables

There is actually a fairly straightforward procedure for setting the configuration via environment variables:

  1. Update the configuration in a running server, so it reflects your requirements
  2. Create, execute and export a backup in the maintenance application for the configuration only
  3. Unzip the zip file and open the file general.configuration/User_Default.properties in it
    • The file contains the custom keys and values of your configuration. You will not need all the values here, but you should be able to find and apply the value you have set.

To create the environment variable names use the following rule:

  • Each environment variable must be prefixed with CONF_
  • Each dot . must be replaced by __ - double underscores.

So the property default.company.description becomes → CONF_default__company__description

Example

version: '2.1'

services:

    cowork:
        image: 'inetsoftware/i-net-cowork:latest'
        restart: 'always'
        ports:
            - 7000:7000

        environment:
            - DEFAULT_PROPFILE=/tmp/defaultConfiguration.properties
            - DEFAULT_CONFIG=User/Default
 
            # Set the externally visible server url ="../../../../un-comment-and-insert-the-correct-url"
            #- CONF_serverURL=https://hostname.company.com:9443/
 
            # Set the license key (un-comment and insert the full license key)
            #- CONF_licensekey=...
 
            # Run the application on a pre-determined port for easier mapping
            - CONF_listener__port=7000
 
            # Customize an option, e.g. the theming colors
            - CONF_theme__themecolors={"@base-color":"#123456","@primary-color":"#428bca"}
 
            # Enable logging, route log to the container log-file
            - CONF_log__engine=true
            - CONF_log__file=/dev/stdout
 
            # Location for automatic backups
            - CONF_BackupLocation=/home/cowork/.i-net software/cowork_User_Default/backup

Advanced Use Case

If there are more specific requirements, such as a pre-filled user database, a custom container should be created

Example: internal access with public account

Using the following compose example you can create a server that is started without any permission restrictions and can be used without further authentication using the public URL context.

version: '2.1'

services:

    cowork:
        image: 'inetsoftware/i-net-cowork:latest'
        restart: 'always'
        ports:
            # Not setting a host port allows to use --scale, but the external port varies
            - 7000:7000

        environment:
            # Otherwise use User/Default
            - DEFAULT_CONFIG=User/Default
 
            # Set the license key (un-comment and insert the full license key)
            #- CONF_licensekey=...
 
            # Run the application on a pre-determined port for easier mapping
            - CONF_listener__port=7000
 
            # Only guest account is active.
            - CONF_authentication__settings=[{"provider"\:"guest"}]
            - CONF_plugins__activated={"webapi.core"\:true}

Example: add PAM authentication and a default user

The following Dockerfile will create a user admin with the password password in a new container.

FROM inetsoftware/i-net-cowork
 
# Switch to root user for installation
USER root
 
# Tools
RUN apk add --update linux-pam
 
# grant pam permissions to everybody
# Create User that we can log in with
RUN chmod +r /etc/shadow \
    && adduser -D -g "User" admin \
    && echo admin:password | chpasswd \
    && ln -s "/etc/pam.d/base-password" "/etc/pam.d/cowork"
 
 
# Enable the system login. By default, the PAM plugin is disabled.
ENV CONF_authentication__settings="[{'provider':'system'},{'provider':'product','userCanRegister':'true'}]"
ENV CONF_plugins__activated="{}"
 
# Switch back to product user
USER cowork

Mounting / Re-using a given configuration

If the data of the container should be persisted beyond restarts, e.g. for new container versions, a volume should be mounted.

The persistence and configuration is located in the home folder of the product user. You should use the following additional options to mount this folder:

-v /folder/to/mount/from:/home/$PRODUCT -e FORCE_IMPORT_CONFIG=0
  • -v /folder/to/mount/from:/home/$PRODUCT - mount the specific folder to the home folder of the product user
  • -e FORCE_IMPORT_CONFIG=0 - specify that the given configuration should not be overwritten

Note: the product user depends on the product you are using. It is determined by the $PRODUCT variable in the container. Possible values are: reporting, pdfc, cowork and helpdesk.

Adding additional fonts

The default container comes with, e.g. the DejaVu font pre-installed. Adding additional fonts, such as the license restricted Microsoft fonts Arial, require building a custom container. You can use the following Dockerfile as a basis.

#############################################################################
# Prepare product
# Note: alpine 3.12 due to issue with newer versions of alpine!
FROM alpine:3.12 as builder
 
RUN apk add --update msttcorefonts-installer \
    && update-ms-fonts
 
FROM inetsoftware/i-net-<PRODUCT>:<TAG>
 
USER "root"
 
# Copy fonts from intermedia builder
COPY --from=builder /usr/share/fonts/truetype/msttcorefonts /usr/share/fonts/truetype/msttcorefonts
 
# Update font cache for product user
USER $PRODUCT
RUN fc-cache -fv /usr/share/fonts

Environment Properties Matrix

Property Name Default Value Description
DEFAULT_PROPFILE /tmp/defaultConfiguration.properties Configuration Properties file for initial setup
DEFAULT_CONFIG User/Default Configuration the server will be started with
FORCE_IMPORT_CONFIG 1 Forces the import of the given configuration, overwriting an already existing one. Set to 0 if a configuration is mounted.
DOCKER_ENTRYPOINT_SCRIPT Additional inline-script to run before starting the server
CONF_systempermission__enabled false The system permissions are deactivated by default. That means any user with a login has access to everything in the system. This property should be customized together with the authentication settings.
CONF_authentication__settings [{'provider':'product','userCanRegister':'true'}] The product login is activated by default and allows new users to be created. This should be customized in a production environment.
CONF_plugins__activated {'authentication.pam':false} The PAM authentication plugin is deactivated by default, because you have to create custom container in order to use it. Only optional plugins have to be enabled with the value true using this settings. To deactivate a non-optional plugin, use the value false.
CONF_prop__name Configuration property for server initialization. prop__name was derived from an actual property prop.name which can be taken from a previous backup.
inet_http_port Set a default HTTP port that overrides the one in the configuration. This is intended for shared cloud persistences
inet_https_port Set a default HTTPS port that overrides the one in the configuration. This is intended for shared cloud persistences
inet_persistence URI of the persistence to use. Currently on MongoDB is supported. Will uses the file persistence if not set.

MongoDB Persistence

Using MongoDB Persistence is recommended in scenarios where no hard drive is available or the file system can disappear together with the server instance. For technical details, please have a look at the documentation.

To configure either persistences the environment variable inet_persistence has to be set up accordingly:

inet_persistence=<PERSISTENCE URI>
 
# MongoDB
inet_persistence=mongodb://(<USERNAME>:<PASSWORD>@)<MONGODB SERVER>/<DATABASE>

If the platform does provide these URIs using environment variables, these have to be forwarded respectively.

Since the configuration is being stored in the persistence it might be required to set the application port to a specific value every time the container starts (e.g. Heroku provides an environment variable for that). This port has to be set using the environment variables: inet_http_port or init_https_port

Docker Compose Example

To bundle a docker container with a MongoDB persistence using Docker Compose, the following docker-compose.yml script can be used as a starting point:

version: '2.1'

services:

    cowork:
        image: 'inetsoftware/i-net-cowork:latest'
        restart: 'always'
        ports:
            # Not setting a host port allows to use --scale, but the external port varies
            - 7000:7000

        environment:
            # Using the System/Default config is mandatory in cloud persistence environments
            - DEFAULT_CONFIG=System/Default
 
            # Set the externally visible server url ="../../../../un-comment-and-insert-the-correct-url"
            #- CONF_serverURL=https://hostname.company.com:9443/
 
            # Set the license key (un-comment and insert the full license key)
            #- CONF_licensekey=...
 
            # Run the application on a pre-determined port for easier mapping
            - CONF_listener__port=7000
 
            # Do not force the application to overwrite a previously imported configuration
            # or other instances using the same MongoDB will have their configuration modified
            - FORCE_IMPORT_CONFIG=0
 
            # Set up the connection the MongoDB persistence
            - inet_persistence=mongodb://root:example@mongo:27017/cowork

    mongo:
        image: mongo
        environment:
            MONGO_INITDB_ROOT_PASSWORD: example
            MONGO_INITDB_ROOT_USERNAME: root
        restart: always

Note: The parameter FORCE_IMPORT_CONFIG should be set to 0 so that the configuration is imported only once versus every time the container is started. This way the configuration may be persisted and re-used on subsequent restarts or in a scaled environment.

Note: Depending on the specific environment there may be some more options that have to be set. Please have a look at the Environment Properties Matrix.

Installing Additional Plugins

Additional plugins can be added to the Docker container either during a custom Dockerfile build or on the fly during container startup. In both cases you can use the install-plugin command of the container:

/usr/share/product $ install-plugin --help
Usage install all Plugins: /bin/install-plugin -p <product> -v <version>
Usage install defined plugins: /bin/install-plugin -p <product> -v <version> <list of plugins to install>
Usage install BETA Plugins: /bin/install-plugin -p <product> -v <version> -b <list of plugins to install>
Usage install additional persistence: /bin/install-plugin -s <type>

Note: Plugin names can be derived, e.g. from the plugin store URL, specifically the path component after /pid: https://store.inetsoftware.de/pid/webapi.corewebapi.core

Note: There are distinct containers available for each persistence type. The MongoDB persistence is installed in the default container that has no additional tag. Available persistences are: mongodb, cosmosdb, dynamodb.

Dockerfile Example

In a Dockerfile you can add the following lines to install a plugin:

# Add Web API plugin 
RUN install-plugin web.api

Docker Compose Example

In a docker-compose.yml you can use the following setup to install a plugin:

version: '2.1'
services:
    service:
        command: >
            sh -c "
            install-plugin web.api &&
            ./startServer.sh -Dclearreports.config=User/Default -Dsetupautoexecution=true
            "

Note: the original startServer.sh command can be determined using docker inspect on an already running container.

Note: The example is incomplete and requires definition of the specific container.

Restarting the Service

In situations where the service is unresponsive, but the container can still be accessed, the server's subprocess can be terminated and restarted without restarting the whole container. In this case, the user has to enter the container using shell and run the following command:

ps xo pid,command | grep exitcode | grep -v grep | awk '{print $1}' | xargs -r kill -TERM

Recovery Manager

The Recovery Manager is a last-resort measure when the server was misconfigured. It can be used to fix configuration issues and remove plugins that produce unrecoverable startup issues. You can also update user information, e.g. fixing group assignments.

Important: The server is completely open to anyone who can access the host IP and port. This person can configure the system with administrative rights. You should consider using an additional firewall to secure the host port and only allow access to your own client host. Note that the -client.ip setting is not sufficient.

Note: Only a minimal set of features is available on the server, to allow you to recover from a startup issue. Not all plugins will be loaded.

Note: Your server must be run using the FORCE_IMPORT_CONFIG=1 environment variable (see mounting). Otherwise, when restarting the original server, it will overwrite the modified configuration.

Here is a step-by-step guide:

  • Stop the server, but do not remove the server from docker.
# in a compose setup
docker compose stop
 
# or using classic docker command
docker stop <container-name>
  • Check, which image the server was started with, e.g. using docker ps | grep <container-name>
  • Check, which configuration the server was running with, e.g. using docker inspect <container-name> | grep DEFAULT_CONFIG or docker exec <container-name> env | grep DEFAULT_CONFIG. By default, that is User/Default
  • Start the recovery server
docker run --rm -it --volumes-from "<container-name>" -p 9999:9999 --entrypoint /bin/sh "<container-image-name>" startRecovery.sh -clearreports.preferredconfig "User/Default" -port 9999 -client.ip "0.0.0.0-255.255.255.255"
  • Access the server using http://<server-ip>:9999/
  • When you are done with the configuration, stop the server using CTRL+c in the console.
  • You can now restart the original service.

Here is a full explanation of the command:

  • docker run –rm -it - we're running an additional sidecar container
  • –volumes-from "<container-name>" - we're mounting the existing volumes from the service container. That is: the home directory, which, by default, holds the persistence and configuration.
  • -p 9999:9999 - we're using the port 9999 to connect to the server externally and internally
  • –entrypoint /bin/sh - the entry point must be updated to the default shell. Otherwise, the container will start by modifying the existing configuration
  • "<container-image-name>" - this must be the same image as your service is running with
  • startRecovery.sh - the recovery entry point script
  • -clearreports.preferredconfig "User/Default" - this is the configuration we want to change. It is important, to have the same configuration as in the original server container. Otherwise, you will not be updating the correct settings.
  • -port 9999 - the internal port the recovery configuration should run on
  • -client.ip "0.0.0.0-255.255.255.255" - an IP access filter which you should definitely adjust to your network settings. If that filter does not match, the recovery configuration will not let you enter. Docker has the peculiarity of not necessarily recognizing the IPs of the environment - in this case the IP of your computer - correctly. It may therefore be necessary to specify a larger network as a share.

Note: The server is completely unsecured. It does not run with https / ssl encryption. It is fully open to any IP accessing this server. You should consider an additional firewall for the server and port to only allow access from your client host.

i-net CoWork
This application uses cookies to allow login. By continuing to use this application, you agree to the use of cookies.


Help - Docker Container Setup