Package your first application¶
Let's take as an example, Matomo web analytics.
- Tired: Write your own image and compose file
- Wired: Use someone else's image (& maybe compose file)
- Inspired: Upstream image, someone else's compose file
- On fire: Upstream compose file
I'm feeling lazy so, luckily for me, Matomo already has an example compose file in their repository! Let's download and edit it:
mkdir matomo && cd matomo wget https://raw.githubusercontent.com/matomo-org/docker/master/.examples/apache/docker-compose.yml -O compose.yml
compose.yml in your favourite editor and have a gander . There are a few things we're looking for -- full list to come -- but a few things we can immediately see are:
- Let's bump the version to
3.8, to make sure we can use all the latest swarm coolness
- We load environment variables separately via abra, so we'll strip out
/var/www/htmlvolume definition on L21 is a bit overzealous; it means a copy of Matomo will be stored separately per app instance, which is a waste of space in most cases. We'll narrow it down according to the documentation -- here, the developers have been nice enough to suggest
configvolumes instead, which is a decent start
- The MySQL passwords are sent as variables which is fine for basic use, but if we replace them with Docker secrets we can keep them out of our env files if we want to publish those more widely.
- The MariaDB service doesn't need to be exposed to the internet, so we can define an
internalnetwork for it to communicate with Matomo.
- Lastly, we want to use
deploy.labelsand remove the
ports:definition, to tell Traefik to forward requests to Matomo based on hostname and generate an SSL certificate.
compose.yml is available here.
Now, create an
.env file (or call it anything else, but remember to specify the
-e option for
TYPE=matomo DOMAIN=matomo.example.com LETS_ENCRYPT_ENV=production SECRET_DB_PASSWORD_VERSION=v1 SECRET_DB_ROOT_PASSWORD_VERSION=v1
Then, open the
DOMAIN you configured (you might need to wait a while for Traefik to generate SSL certificates) to finish the set-up. Luckily, this container is (mostly) configurable via environment variables -- if we want to auto-generate the configuration we can use a
config and / or a custom
coop-cloud/mediawiki for examples of both).
How apps are versioned¶
Co-op Cloud follows the version scheme of the applications we're packaging, as
far as possible; for example, version
1.13.4 of our Gitea recipe
1.13.4 of Gitea. We're trying not to invent a new versioning
This approach is still work-in-progress.
Versions are based on Docker image tags: we don't currently have a plan for apps
which only publish a
master tag, for instance.
Versioning different services¶
Most apps have underlying services like databases and/or caches.
When there's a new version of one of these services, but not the "main" service,
we add/increment the
_<revision> part at the end of the version.
So, if you are still on
1.13.4 for Gitea, but you have
mariadb:10.5, then the Gitea recipe package version would be
If you run
abra recipe gitea versions, you'll see that there are a few
available versions of the
gitea recipe, two with the same version of the
1.14.1-rootless: - app (gitea/gitea:1.14.1-rootless, 6244e9fc) - db (mariadb:10.5, 36288c67) 1.14.1-rootless_1: - app (gitea/gitea:1.14.1-rootless, 6244e9fc) - db (mariadb:10.6, 718cb856) 1.14.2-rootless: - app (gitea/gitea:1.14.2-rootless, bedf8d12) - db (mariadb:10.6, 718cb856)
1.14.1-rooless_1 differ only in their version
mariadb service. If there had been several updates to the
image in between updates to the
gitea image, there might have also been
1.14.1-rooless_3 -- this is more likely with recipes which
include services with several different images.
Not all of these updates will be released as installable Co-op Cloud recipes
-- in this example, there's no version with
mariadb:10.5. If you need a specific combination, create a pull request or
issue in the repository for the app recipe!
--- kind: pipeline name: recipe release steps: - name: release a new version image: decentral1se/drone-abra:latest settings: command: recipe YOURRECIPE release deploy_key: from_secret: abra_bot_deploy_key
- name: notify coopcloud-dev on failure image: plugins/matrix settings: homeserver: https://matrix.autonomic.zone roomid: "IFazIpLtxiScqbHqoa:autonomic.zone" userid: "@autono-bot:autonomic.zone" accesstoken: from_secret: autono_bot_access_token depends_on: - deployment when: status: - failure
Packaging style guide¶
- Please don't use
&imageYAML repeat anchors on the
image: ...key because our
recipe releaselogic does not handle it (see #172)