Getting Started with Docker

Create Environment

First you have to create a website on your server. Our website module provides everything you need to manage, deploy and run your website. Every Website is type and environment based, which means you have to select a particular type and environment.

  1. Log in to cockpit.opsone.ch

  2. Choose your server or create a new one

  3. Go to websites, and create a new one

  1. Select website type Docker and configure Proxy pass to your Docker containers port

The Proxy pass value must also include the protocol such as http or https. An example of a correct value: http://127.0.0.1:8080

Access with SSH

On the server you can work with SSH. Due to security reasons, we allow key based logins only.

  1. If you don’t have an SSH key: Create an SSH key pair

  2. Add your SSH Public Key in the Cockpit: Either for the whole server or within the website.

  3. Now you can log in via SSH. Username is your chosen website name.

Tip

Wondering why your existing SSH key is not working? Maybe it does not meet our minimum requirements.

Run Docker Container

# run your docker container (nginx as example)
$ docker run --detach --restart always --publish 127.0.0.1:8080:80 nginx

You can use any free port. In this example we expose our docker container at 127.0.0.1:8080.

Tip

Always start your containers with --restart always to make sure they are up and running again after a automatic or planned reboot.

Tip

You can alternatively use docker-compose (v1) or docker compose (v2) to set up your docker container. Additional information on docker compose is available in the Docker manual.

Tip

For the container to be accessible from the outside via reverse proxy, the selected port must match the one configured in Proxy pass.

Expose Port Externally

In general, we do not recommend to expose Docker ports to the world for security reasons, but use a proxy website in front instead. Still, there are use cases which this is required tough:

  • by default, exposed ports are bound to 127.0.0.1

  • bind your port to the desired interface explicitly: --publish 192.168.1.1:2222:22

  • allow external access to the port with a custom firewall rule (see Custom Rule)

User Namespace Isolation

For security reasons, we run Docker in a isolated namespace (Details within the Docker manual).

  • user and group IDs within the container are mapped to non-existing IDs on the host

  • direct bind mounts are not allowed

  • use volumes instead

Tip

We know of certain setups where it is not possible to have userns remapping enabled. If you encounter this problem, please contact us and we will disable userns remap for your system after we checked your requirements.

Access Local MariaDB

For security reasons, we only allow access to the MariaDB from localhost, but sometimes it is desirable to use the local MariaDB from inside a Docker container.

To achive this you need to modify the Custom JSON Server Level Configuration as follows.

Tip

Make sure to expand any existing Custom JSON objects, otherwise you will overwrite them!

Add a new MariaDB user that is allowed to access MariaDB from the Docker IP range. The <MARIADB_USER> can be freely named, but must be consistent across the following options, i tend to name it the same as the database, for consistency.

"database::users": {
  "<MARIADB_USER>@172.16.%.%": {
    "password": "<MARIADB_PASSWORD>"
  }
}

Grant this new user premission to an existing MariaDB.

"database::grants": {
  "<MARIADB_USER>@172.16.%.%": {
    "user": "<MARIADB_USER>@172.16.%.%",
    "database": "<EXISTING_DATABASE>",
    "table": "*"
  }
}

And finally in the Firewall Rules allow the Docker IP range to access MariaDB.

"nftables::rules": {
  "accept incoming MariaDB connection from Docker": {
    "chain": "input",
    "rule": "tcp dport 3306 ip saddr 172.16.0.0/12 accept"
  }
}

Now you can access MariaDB from within a Docker container with the <MARIADB_USER> and <MARIADB_PASSWORD> configured above, as host use the FQDN from the Server.

Persisting Data

To persist data in docker containers, volumes should be used instead of bind mounts otherwise permission conflicts will occur.

In the following example we start a nginx container and create a volume nginx-www that persists the data in /usr/share/nginx/html and is initally populated with the data from the container in the defined path. For more Information about docker volumes take a look at the docker documentation.

 # run nginx with persisted www-root
 docker run --detach --restart always --publish 127.0.0.1:8080:80 --name nginx --volume nginx-www:/usr/share/nginx/html nginx

# list volumes
docker volume ls

# remove volumes
docker volume rm <VOLUME NAME>

# copy folder ~/www from host into the docker volume
docker cp ~/www nginx:/usr/share/nginx/html

There are many ways you can populate your volumes. We recommend using volumes for data that is modified by the application or the user. For the application itself or for configuration files, we recommend putting them in the container during the build phase