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 based, which means you have to select a particular Type.

  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

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

You can use any free, non-privileged port above 1024. In this example, we expose our Docker container at 127.0.0.1:${WEBSITE_PORT}. When you create a Docker website, a random port is generated and available via the ${WEBSITE_PORT} environment variable.

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

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 to set up your Docker container. Additional information on Docker Compose is available in the Docker manual.

Warning

docker-compose (v1) is no longer supported by Docker. Please use docker compose (v2) instead.

Expose Trough Front Proxy

To expose your Docker container with an HTTP service to the world, you need to configure a proxy. A example is provided in the .htaccess created by default. For the container to be accessible from the outside, the selected port must match the one specified in your Docker run command or Docker Compose file. You can use the WEBSITE_PORT environment variable in both .htaccess and Docker / Docker Compose configuration to dynamically bind your service to a random port.

Expose Port Externally

In general, we do not recommend exposing Docker container ports to the world for security reasons, but use a proxy website in front instead. Still, there are usecases for 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 Rules)

Docker Rootless

For security reasons, we use Docker in rootless mode, which means:

  • containers are run in a isolated user namespace

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

  • you only see the containers of your website user

  • direct bind mounts are not allowed (use volumes instead)

Tip

We know of certain setups where it is not possible to use rootless mode (e.g. Docker Swarm). If you encounter this problem, please contact us and we will check for a possible solution.

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 achieve this,you need to modify the Custom JSON Server Level Configuration as follows.

Add a new MariaDB user that is allowed to access MariaDB from the server’s own public IP. The <MARIADB_USER> can be freely named but must be consistent across the following options.

"database::users": {
  "<MARIADB_USER>@<SERVER_HOSTNAME>": {
    "password": "<MARIADB_PASSWORD>"
  }
}

Grant this new user premission to an existing database:

"database::grants": {
  "<MARIADB_USER>@<SERVER_HOSTNAME>": {
    "user": "<MARIADB_USER>@<SERVER_HOSTNAME>",
    "database": "<EXISTING_DATABASE>",
    "table": "*"
  }
}

Now you can access the database from within a Docker container by using the servers hostname, and the user/password configured above.

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 initially 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.