6.6 KiB
title |
---|
Packager guide |
Package your first application
Let's take as an example, Matomo web analytics.
We'll be making a Docker "swarm-mode" compose.yml
file.
- 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.
Like a lot of compose files, it's intended for use with docker-compose
, instead of "swarm mode", but it should be a good start.
First, let's create a directory with the files we need:
abra recipe create matomo
cd ~/.abra/apps/matomo
Then, let's download and edit the docker-compose.yml
file:
mkdir matomo && cd matomo
wget https://raw.githubusercontent.com/matomo-org/docker/master/.examples/apache/docker-compose.yml -O compose.yml
Open the compose.yml
in your favourite editor and have a gander 🦢. There are a few things we're looking for -- full list to come -- but some immediate changes could be:
- 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
env_file
. - The
/var/www/html
volume 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 suggestlogs
andconfig
volumes 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
internal
network for it to communicate with Matomo. - Lastly, we want to use
deploy.labels
and remove theports:
definition, to tell Traefik to forward requests to Matomo based on hostname and generate an SSL certificate.
The resulting compose.yml
is available here.
!!! note "Running Co-op Cloud server required!"
The rest of this guide assumes you have a Co-op Cloud server going -- we'll use `swarm.example.com`, but replace it with your own server address.
Head over to [the deployment guide](./deploy.md) if you need help setting one up.
Now, we're ready to create a testing instance of Matomo:
abra app new matomo --secrets \
--domain matomo.swarm.example.com \
--server swarm.example.com \
--app-name mygreatapp
Depending on whether you defined any extra environment variables -- we didn't so
far, in this example -- you might want to run abra app mygreatapp config
to
check the configuration.
Otherwise, or once you've done that, go ahead and deploy the app:
abra app mygreatapp deploy
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 entrypoint
(see 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
contains version 1.13.4
of Gitea. We're trying not to invent a new versioning
scheme.
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 latest
or 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.6
upgraded
from mariadb:10.5
, then the Gitea recipe package version would be 1.13.4_1
.
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
gitea
image:
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)
Versions 1.14.1-rootless
and 1.14.1-rooless_1
differ only in their version
of the mariadb
service. If there had been several updates to the mariadb
image in between updates to the gitea
image, there might have also been
1.14.1-rooless_2
, 1.14.1-rooless_3
-- this is more likely with recipes which
include services with several different images.
!!! note
Not all of these updates will be released as installable Co-op Cloud recipes
-- in this example, there's no version with `gitea:1.14.2-rootless` and
`mariadb:10.5`. If you need a specific combination, create a pull request or
issue in the repository for the app recipe!
Automation
Upgrades
See autonomic-cooperative/renovate-bot.
Releases
---
kind: pipeline
name: recipe release
steps:
- name: release a new version
image: thecoopcloud/drone-abra:latest
settings:
command: recipe YOURRECIPE release
deploy_key:
from_secret: abra_bot_deploy_key
Failure notifications
- 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
Github mirroring
See auto-mirror.
Packaging style guide
- Please don't use
&image
YAML repeat anchors on theimage: ...
key because ourrecipe release
logic does not handle it (see #172)