Package: backplane
backplaneWebsite—Documentation—Source CodeA batteries-included launchpad for your Docker Compose services - with free SSL and Git-based continuous delivery. Run any Docker appmanuallyor frombackplane's app-storein no time.Get started🚀 Check out ourExamplessection for quick-start templates forWordpress,Sonarqubeand morepipinstallbackplane
backplaneinit
backplaneupYou can now visit the dashboards ofTraefikandPortainerin your browser:traefik.127-0-0-1.ns0.coportainer.127-0-0-1.ns0.coConfigure your Docker Compose servicesExposing one of your services throughbackplaneis easy:add it to thebackplaneDocker networkadd a labelbackplane.enabledwith valuetruebackplanewill automatically pick up the service's name (e.g.whoami) and exposes it as a subdomain of yourbackplane domain(defaults to127-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, seeAdvanced configurationversion:"3.3"services:whoami:image:"traefik/whoami"container_name:"whoami"networks:-backplanelabels:-"backplane.enabled=true"networks:backplane:external:trueYour service will be exposed ashttp://whoami.127-0-0-1.ns0.co.Use backplane with HTTPSUse--httpsand add a mail address for LetsEncrypt on installation to enable additional security for your applications. An optional--domaincan be set on installation (defaults to$SERVER_IP.ns0.co, e.g.193-43-54-23.ns0.coif--httpsis set).backplaneinit--https--mailletsencrypt@mydomain.com[--domainmydomain.com]backplaneupThis enables the following additional features:access your Docker Compose services as subdomains ofmydomain.comautomatic 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 redirectsane security defaultsThe Docker Compose stack definition doesn't change from the one without--https.backplanedeals with the necessary configuration.version:"3.3"services:whoami:image:"traefik/whoami"container_name:"whoami"networks:-backplanelabels:-"backplane.enabled=true"networks:backplane:external:trueYour container will be exposed ashttps://whoami.mydomain.com.AuthenticationThe default username for authentication with backplane services isadmin, the default password isbackplane.Assuming you don't want to roll with the defaults when runningbackplaneon a public server, you can add--userand--passwordto theinitcommand to specify your own values.backplaneinit--https--usertestuser--passwordtestpasswordAuthentication for your servicesTraefik comes with aBasicAuth Middlewarethat 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:-backplanelabels:-"backplane.enabled=true"-"traefik.http.routers.whoami.middlewares=auth@docker"networks:backplane:external:trueWhen 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 withstandardDocker Compose stacks. We also plan to integrate with Portainer's templating system to make installing applications even easier.backplaneoffers multiple ways to launch your applications. They all expect your application to live inside a repository (i.e. a directory).backplanecan deploy from a plain directory or local and remote git repositories.backplaneimplements a simple workflow arounddocker-composeto "install" your applications to a Docker engine it has access to. Basicallybackplanedoes this:load variables from.envaugment with global configuration (i.e.BACKPLANE_DOMAIN=127-0-0-1.ns0.co)use--buildif necessary (i.e. if there's abuild:section indocker-compose.yml)rundocker-compose up -dbackplane(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 localbackplaneconfig (default:~/.backplane/contexts/default/backplane.yml).An application that can be installed withbackplaneshould contain:adocker-compose.ymlfilean optional.envfile configuring your stackthe application codean optionalDockerfileto build the application (backplaneexpects thebuild:section of thedocker-compose.ymlfile to be correctly configured)Here are a few examples:Grafana LokiDocker Registrybackplane itselfWith the CLIbackplanecan 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:backplaneinstallOptional arguments:--name: the name of your application (translates to thedocker-composeproject, 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 wherebackplanecan find the application; defaults to the current directory--compose-file(or-c): the compose file to be used for installation (defaults todocker-compose.yml)app name: if specified,backplaneignores thepathargument and tries to install the application by cloning the repository from the given source to~/.backplane/contexts/default/apps/$NAME, where$NAMEequals to theNAMEargument (if given) or defaults to the name of the git repositoryExampleslocal directory, custom name:backplaneinstall--namemy-awesome-app-beta--from$HOME/development/my-awesome-appsets the application name tomy-awesome-app-betainstalls the application from$HOME/development/my-awesome-appremote git repository, default name:backplaneinstall--fromhttps://github.com/backplane-apps/registrycloneshttps://github.com/backplane-apps/registryto~/.backplane/contexts/default/apps/registryinstalls the application from~/.backplane/contexts/default/apps/registrylocal git repository, default name:backplaneinstall--from$HOME/development/my-awesome-appclones$HOME/development/my-awesome-appto~/.backplane/contexts/default/apps/my-awesome-appinstalls the application from~/.backplane/contexts/default/apps/my-awesome-appThis mechanism is used by thebackplaneservice running alongside Traefik and Portainer. This service enables you togit pushto yourbackplane. Read more about this in the next section.backplane app registry, default name:We're building a central registry for backplane-comtatible applications onGitHub. Installing one of those is as easy as running:backplaneinstalllokicloneshttps://github.com/backplane-apps/lokito~/.backplane/contexts/default/apps/lokiinstalls the application from~/.backplane/contexts/default/apps/lokiOur 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 gitbackplanecontains 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 remotebackplanewhere 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 remotebackplanehosts 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 usebackplaneto deploy and run your Docker Compose services on that server.Let's assume our remotebackplanehas the following attributes:ip: 1.2.3.4backplane-domain: 1-2-3-4.ns0.cohttps: enabledATTENTION: the Git Repository service uses~/.sshof the user that initializedbackplane(i.e.backplane init) to determine theauthorized_keysthat are eligible to push tobackplanevia git. Make sure to add all relevant public keys to~/.ssh/authorized_keyson yourbackplanehostTIP:cat ~/.ssh/id_rsa.pub | pbcopycopies your SSH public key to your clipboardUpdate your ssh configAdd the following to your local~/.ssh/configfile. This allows you to reach your remotebackplaneunderbackplanewithout further configuration.HostbackplaneHostName1.2.3.4UserbackplanePort2222Wrapup:our remotebackplane(on 1.2.3.4) is now available asbackplanewhen connecting with sshbackplaneruns on port 2222; ports ins git remote-urls can cause problems which is why wemaskport and ip behind thebackplanehostnameNOTE: replace the value of "HostName" with your server's IP or hostname. For convenience, we're usingns0here to provide wildcard DNS on IP basisUpdate your git remoteAssuming your application repository is calledwhoami, this is how you add your remotebackplaneto your git remotes:gitremoteaddorigin"git@backplane:whoami"Wrapup:our previously configured remotebackplanebecomes our new git remote-urlwe're connecting as usergitour repository on the remote it calledwhoamiDeploy to your serverHINT: as you see, we're using theConventional Commitformat here. This will likely be a part of backplane's future roadmap in the form of automated versioning based on commits. Just FYI.gitcommit-am"feat: figured out who I am"gitpushbackplanemasterThat's it!backplanewill build and deploy your application and expose it automatically ashttps://whoami.1-2-3-4.ns0.co.What is backplanebackplaneconsists of 3 main services running as Docker containers on your host:Traefik, a very popular, cloud-native reverse-proxyPortainer, a very popular management interface for Dockerbackplane, this softwareIt aims to provide simple access to core prerequisites of modern app development:Endpoint exposureContainer managementDeployment workflowsTo develop and run modern web-based applications you need a few core ingredients, like a reverse-proxy handling request routing, a way to manage containers and a way to deploy your code.backplaneoffers this for local development as well as on production nodes in a seemless way.backplanemakes it easy to bypass long CI pipelines and deploy your application to a remote backplane host with ease.backplaneis mainly aimed at small to medium sized development teams or solo-developers that don't require complex infrastructure. Use it for rapid prototyping or simple deployment scenarios where the full weight of modern CI/CD and PaaS offerings just isn't bearable.You can migrate from local development to production with a simplegit pushwhen usingbackplaneon both ends. Think of it as a micro-PaaS that you can use locally.What backplane is NOTa PaaS solution; backplane only provides a well-configured reverse-proxy and a management interface for containersmeant for production use. You can, though, but at your own riskAdvanced configurationbackplaneis only a thin wrapper around Traefik and Portainer. If you require more complex routing scenarios or have more complex service setups (e.g. multiple domains per container), simply use Traefik's label-based configuration.Read morein the docs.Expose containers with non-standard portsbackplaneexpects your services to listen to port 80 inside their containers. If that is not the case, you need to tell the backplane about it. Add the following additional labels to tell backplane your service is accessible on port 9000:labels:-backplane.enabled=true-"traefik.http.services.custom-http.loadbalancer.server.port=9000"ExamplesIn theexamplesdirectory you'll find examples showing how to integrate backplane with your existing servicesChange to any of the example folders and runbackplane install. The example'sREADMEwill hold additional information on how to use it.DevelopmentDependenciespipinstallpoetry
poetryshell
poetryinstallBuildpoetrybuildBuild Dockerdockerbuild--build-argBUILD_DATE=$(date-u+'%Y-%m-%dT%H:%M:%SZ')--build-argBUILD_VERSION=$(backplane--version)--build-argVCS_REF=$(gitrev-parse--shortHEAD)-twearep3r/backplane.
dockertagwearep3r/backplanewearep3r/backplane:$(backplane--version)dockerpushwearep3r/backplane:$(backplane--version)dockertagwearep3r/backplanewearep3r/backplane:latest
dockerpushwearep3r/backplane:latestMulti-Archdockerbuildxls
dockerbuildxcreate--namewearep3r--use
dockerbuildxinspect--bootstrap
dockerbuildxbuild--platformlinux/amd64,linux/arm64Generate releasesemantic-releaseversionPublish releasesemantic-releasepublishAuthorFabian Peter,p3r.