Docker Compose

Docker Compose

Docker Compose builds on the docker plugin integration.

We will explore two ways of running border0 connector with docker compose

  1. as vHost service outside of docker-compose scope
  2. as one of services described in docker compose file

This document focuses on the second option or running border0 connector as part of our docker-compose setup
We will create 4 containers in a single flat network setup

  • border0 connector
  • shell server(ssh)
  • nginx server (http)
  • mysql server (database)

working directory

For simplicity and documentation purposes, we will create a temporary directory. All files mentioned from this point should be placed into that directory.

border0 binary

Before we start we need to obtain border0 binary.

You can obtain the binary from our downloads page
Or follow our HOWTO: Install CLI tool

border0.yaml config file

In this step we will create a minimal configuration for border0 connector
with your favourite editor create a border0.yaml using following example:

  name: "d0kr-lab"

  token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.ey<...>J9.qJ75mbolje96zpD9gnOnhCKTSBoEjIGDdMMeteZ7RJQ

# Built in SSH Server feature as bastion
  - d0kr-lab-bastion:
      type: ssh
      sshserver: true
      policies: [docker-policy]

  - group: docker_team
    policies: [docker-policy]


Please see our "Creating Access Tokens" howto for details on managing tokens


One of the ways to handle admin authentication is to pass the token via BORDER0_ADMIN_TOKEN environment variable


  • export BORDER0_ADMIN_TOKEN=eyJh<...>JQ ; border0 socket ls
  • BORDER0_ADMIN_TOKEN=eyJh<...>JQ border0 socket ls

Create the Policy

By default all your sockets have default org policy applied, in our example we are using a custom policy especially for docker plugin called docker-policy
to create our custom policy we can use the CLI or portal

border0 policy add --name docker-policy

example policy we can use, please update your access parameters

  "version": "v1",
  "action": [
  "condition": {
    "who": {
      "email": [
        "[email protected]",
        "[email protected]"
      "domain": [
    "where": {
      "allowed_ip": [
    "when": {
      "after": "2022-10-17T00:00:00Z"

Details on creating policies can be found here: Policies as well as Creating a custom policy

Containers for sockets

For our docker-compose setup we are going to create 3 containers, one for each of the main socket types.
HTTP and Database containers will be based off stock nginx and mysql images but SSH server requires additional configuration

Dockerfile.ssh (shell server container)

Just like in Access to an SSH server guide, download your border0 organisation public Certificate

border0 organization show | grep ecdsa-sha2-nistp256 | awk '{print $5,$6}' > 

with your favourite editor create a Dockerfile.ssh using following example:

FROM ubuntu:18.04
RUN apt-get update

RUN apt-get install -y openssh-server
RUN mkdir /var/run/sshd

RUN echo 'root:root' |chpasswd

RUN sed -ri 's/^#?PermitRootLogin\s+.*/PermitRootLogin yes/' /etc/ssh/sshd_config
RUN sed -ri 's/UsePAM yes/#UsePAM yes/g' /etc/ssh/sshd_config

RUN echo "TrustedUserCAKeys /etc/" >>/etc/ssh/sshd_config
COPY /etc/
RUN echo "AuthorizedPrincipalsFile %h/.ssh/authorized_principals" >>/etc/ssh/sshd_config
RUN mkdir -p /root/.ssh
RUN echo "mysocket_ssh_signed" > /root/.ssh/authorized_principals

RUN apt-get install -y iproute2 net-tools mtr-tiny iperf3 nmap


CMD    ["/usr/sbin/sshd", "-D", "-e"]

Border0 Docker Image

We will use our Docker image we publish via GitHub Container Registry (Here)


For details on how to install docker and docker-compose please refer to the official documentation page


Last but not least, with your favourite editor create a docker-compose.yml using following example:

version: "3.3"

    image: ""
    command: ["connector", "start", "--config", "/border0.yaml"]
    container_name: "border0"
#    environment:
#      - BORDER0_ADMIN_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.ey<...>J9.qJ75mbolje96zpD9gnOnhCKTSBoEjIGDdMMeteZ7RJQ
      - "/var/run/docker.sock:/var/run/docker.sock:ro"
      - "./border0.yaml:/border0.yaml:ro"

      - border0
    image: "nginx:latest"
    container_name: "ngx-srv0"
      - "80:80"
      - "border0_80=type=http,port=80,group=docker_team"

      - border0
      context: "."
      dockerfile: "Dockerfile.ssh"
    container_name: "shell-server0"
      - "1022:22"
      - "border0_22=type=ssh,port=22,group=docker_team"

      - border0
    image: "mysql:latest"
    container_name: "mysql-server0"
    - MYSQL_ROOT_PASSWORD=my-secret-pw
      - "3306:3306"
      - "border0_db01=type=database,port=3306,group=docker_team,upstream_type=mysql,upstream_username=root,upstream_password=my-secret-pw"

Build and Start

The final steps are building and starting our compose.

Verify you have all the required files created:

File NameNotes
border0border0 binary
border0.yamlborder0 connector yaml configuration
Dockerfile.sshssh server container definition
docker-compose.ymlthe docker-compose file for our environment

Build all the components

user@host:~$ docker-compose build
border0 uses an image, skipping
http-server0 uses an image, skipping
database-server0 uses an image, skipping
Building ssh-server0
[+] Building 0.3s (18/18) FINISHED                                                                                                                                                                                                                                              
=> exporting to image                                                                                                                                                                                                                                                     0.0s
 => => exporting layers                                                                                                                                                                                                                                                    0.0s
 => => writing image sha256:69eecc470da6c4a3db589f86ae0676c0c764ab60bbae49dd2e857f84ae23a2c8                                                                                                                                                                               0.0s
 => => naming to

Our environment is ready to be bough up

user@host:~$ docker-compose pull && docker-compose up
tarting border0 ... done
Starting ngx-srv0      ... done
Starting shell-server0 ... done
Starting mysql-server0 ... done
Attaching to border0, shell-server0, ngx-srv0, mysql-server0
mysql-server0       | 2023-06-07 14:15:43+00:00 [Note] [Entrypoint]: Entrypoint script for MySQL Server 8.0.32-1.el8 started.
border0             | 2023/06/07 14:15:42 starting the connector service
shell-server0       | Server listening on port 22.
ngx-srv0            | 2023/06/07 14:15:43 [notice] 1#1: nginx/1.23.3
ngx-srv0            | 2023/06/07 14:15:43 [notice] 1#1: built by gcc 10.2.1 20210110 (Debian 10.2.1-6) 
ngx-srv0            | 2023/06/07 14:15:43 [notice] 1#1: OS: Linux 5.19.0-43-generic
border0             | 2023/06/07 14:15:43 creating a socket: d0kr-lab-bastion
mysql-server0       | 2023-06-07 14:15:43+00:00 [Note] [Entrypoint]: Switching to dedicated user 'mysql'
mysql-server0       | 2023-06-07 14:15:43+00:00 [Note] [Entrypoint]: Entrypoint script for MySQL Server 8.0.32-1.el8 started.
mysql-server0       | 2023-06-07T14:15:44.431451Z 0 [System] [MY-010931] [Server] /usr/sbin/mysqld: ready for connections. Version: '8.0.32'  socket: '/var/run/mysqld/mysqld.sock'  port: 3306  MySQL Community Server - GPL.
border0             | Welcome to
border0             | d0kr-lab-bastion - ssh://
border0             | 
border0             | =======================================================
border0             | Logs
border0             | =======================================================
border0             | 2023/06/07 14:15:53 creating a socket: http-ngx-srv0-d0kr-lab
border0             | 2023/06/07 14:15:53 creating a socket: database-mysql-server0-d0kr-lab
border0             | 2023/06/07 14:15:53 creating a socket: ssh-shell-server0-d0kr-lab
border0             | Welcome to
border0             | database-mysql-server0-d0kr-lab - database://
border0             | 
border0             | =======================================================
border0             | Logs
border0             | =======================================================
border0             | Welcome to
border0             | http-ngx-srv0-d0kr-lab -
border0             | 
border0             | =======================================================
border0             | Logs
border0             | =======================================================
border0             | Welcome to
border0             | ssh-shell-server0-d0kr-lab - ssh://
border0             | 
border0             | =======================================================
border0             | Logs
border0             | =======================================================
border0             | 2023/06/07 14:16:13 new ssh session for [email protected] (as user root)
shell-server0       | Accepted publickey for root from port 57942 ssh2: ECDSA-CERT SHA256:9Iy4qVca/VDHZDfdySmLVlrcvAzgTnUHOaZlk8J10uE ID [email protected] (serial 13917293297557563847) CA ECDSA SHA256:VpiD8qNHIlAKhxFWDW2WIaHOKVIEEiyu5wR3IRoPjUY