<div> <img align="left" src="https://raw.githubusercontent.com/wearep3r/backplane/master/logo.png" width="175" alt="logo" /> <h1 align="left">backplane</h1> </div>

Website — Documentation — Source Code

A batteries-included launchpad for your Docker Compose services - with free SSL and Git-based continuous delivery. Run any Docker app manually or from backplane's app-store in no time.

Get started

🚀 Check out our Examples section for quick-start templates for Wordpress, Sonarqube and more

pip install backplane
backplane init
backplane up

You can now visit the dashboards of Traefik and Portainer in your browser:

Configure your Docker Compose services

Exposing one of your services through backplane is easy:

add it to the backplane Docker network
add a label backplane.enabled with value true

backplane will automatically pick up the service's name (e.g. whoami) and exposes it as a subdomain of your backplane domain (defaults to 127-0-0-1.ns0.co).

NOTE: this assumes that your service is accessible on port 80 inside the container. If that is NOT the case, see Advanced configuration

version: "3.3"

services:
  whoami:
    image: "traefik/whoami"
    container_name: "whoami"
    networks:
      - backplane
    labels:
      - "backplane.enabled=true"

networks:
  backplane:
    external: true

Your service will be exposed as http://whoami.127-0-0-1.ns0.co.

Use backplane with HTTPS

Use --https and add a mail address for LetsEncrypt on installation to enable additional security for your applications. An optional --domain can be set on installation (defaults to $SERVER_IP.ns0.co, e.g. 193-43-54-23.ns0.co if --https is set).

backplane init --https --mail letsencrypt@mydomain.com [--domain mydomain.com]
backplane up

This enables the following additional features:

access your Docker Compose services as subdomains of mydomain.com
automatic SSL for your Docker Compose services through LetsEncrypt (HTTP-Validation, so this doesn't work on your developer machine unless you deal with the necessary port-forwardings)
automatic HTTP to HTTPS redirect
sane security defaults

The Docker Compose stack definition doesn't change from the one without --https. backplane deals with the necessary configuration.

version: "3.3"

services:
  whoami:
    image: "traefik/whoami"
    container_name: "whoami"
    networks:
      - backplane
    labels:
      - "backplane.enabled=true"

networks:
  backplane:
    external: true

Your container will be exposed as https://whoami.mydomain.com.

Authentication

The default username for authentication with backplane services is admin, the default password is backplane.

Assuming you don't want to roll with the defaults when running backplane on a public server, you can add --user and --password to the init command to specify your own values.

backplane init --https --user testuser --password testpassword

Authentication for your services

Traefik comes with a BasicAuth Middleware that you can use to protect your services with the username and password configured above. All you need to do is to activate the Traefik middleware for your service:

version: "3.3"

services:
  whoami:
    image: "traefik/whoami"
    container_name: "whoami"
    networks:
      - backplane
    labels:
      - "backplane.enabled=true"
      - "traefik.http.routers.whoami.middlewares=auth@docker"

networks:
  backplane:
    external: true

When initalized with --https, authentication will be activated for Traefik and Portainer automatically.

Deploy to backplane (Experimental)

NOTE: this is still WIP and subject to change. We try to provide an unopinonated wrapper around docker-compose with a few "augmentations" that is fully compatible with standard Docker Compose stacks. We also plan to integrate with Portainer's templating system to make installing applications even easier.

backplane offers multiple ways to launch your applications. They all expect your application to live inside a repository (i.e. a directory). backplane can deploy from a plain directory or local and remote git repositories.

backplane implements a simple workflow around docker-compose to "install" your applications to a Docker engine it has access to. Basically backplane does this:

load variables from .env
augment with global configuration (i.e. BACKPLANE_DOMAIN=127-0-0-1.ns0.co)
use --build if necessary (i.e. if there's a build: section in docker-compose.yml)
run docker-compose up -d

backplane (as of now) does not take care of the lifecycle of the application. To interface with it, use the bundled Portainer to manage your application from a UI or fall back to standard docker/docker-compose tooling.

Installed applications will be saved to your local backplane config (default: ~/.backplane/contexts/default/backplane.yml).

An application that can be installed with backplane should contain:

a docker-compose.yml file
an optional .env file configuring your stack
the application code
an optional Dockerfile to build the application (backplane expects the build: section of the docker-compose.yml file to be correctly configured)

Here are a few examples:

With the CLI

backplane can deploy an application directly from its repository directory. Assuming your application provides the necessary files, just run the following command from within your application directory:

backplane install

Optional arguments:

--name: the name of your application (translates to the docker-compose project, i.e. -p NAME); defaults to the name of the application directory (i.e. $PWD)
--to (or -t): the destination path of your application; defaults to the current directory (i.e. $PWD)
--from (or -f): a git repository, directory or URL where backplane can find the application; defaults to the current directory
--compose-file (or -c): the compose file to be used for installation (defaults to docker-compose.yml)
app name: if specified, backplane ignores the path argument and tries to install the application by cloning the repository from the given source to ~/.backplane/contexts/default/apps/$NAME, where $NAME equals to the NAME argument (if given) or defaults to the name of the git repository

Examples

local directory, custom name:

backplane install --name my-awesome-app-beta --from $HOME/development/my-awesome-app

sets the application name to my-awesome-app-beta
installs the application from $HOME/development/my-awesome-app

remote git repository, default name:

backplane install --from https://github.com/backplane-apps/registry

clones https://github.com/backplane-apps/registry to ~/.backplane/contexts/default/apps/registry
installs the application from ~/.backplane/contexts/default/apps/registry

local git repository, default name:

backplane install --from $HOME/development/my-awesome-app

clones $HOME/development/my-awesome-app to ~/.backplane/contexts/default/apps/my-awesome-app
installs the application from ~/.backplane/contexts/default/apps/my-awesome-app

This mechanism is used by the backplane service running alongside Traefik and Portainer. This service enables you to git push to your backplane. Read more about this in the next section.

backplane app registry, default name:

We're building a central registry for backplane-comtatible applications on GitHub. Installing one of those is as easy as running:

backplane install loki

clones https://github.com/backplane-apps/loki to ~/.backplane/contexts/default/apps/loki
installs the application from ~/.backplane/contexts/default/apps/loki

Our plan is to keep these apps compatible to Portainer's templating system to make them available as one-click installations from within the Portainer UI. One issue we currently face with this is that Portainer templates are only compatible with docker-compose configuration version "2".

With git

backplane contains a small Git Repository service with a dead-simple CI/CD workflow for your applications. The following section explains how to push your code to a remote backplane where it then will be automatically built and deployed according to the workflows described in the previous sections.

This might also make sense on local development machines, but is primarily meant as a method to deploy your applications to remote backplane hosts in a safe way. For the following parts we assume that you have a server somewhere in the internet that you have access to via SSH (public-key authentication) and you want to use backplane to deploy a

Backplane

Install / Use

README