docs.coopcloud.tech/docs/maintainers/tutorial.md

68 lines
3.9 KiB
Markdown
Raw Normal View History

2021-03-26 00:01:19 +00:00
---
2022-01-26 10:47:44 +00:00
title: New maintainers tutorial
2021-03-26 00:01:19 +00:00
---
2021-09-30 13:15:44 +00:00
## Package your first recipe
2021-05-31 20:01:25 +00:00
2022-02-03 16:42:31 +00:00
Packaging a recipe is basically knowing a bag of about 20 tricks. Once you learn them all, there is nothing more to learn. It can seem daunting at first but it's simple and easy to do once you know the tricks.
2021-05-31 20:01:25 +00:00
2022-02-03 16:42:31 +00:00
Let's take as an example, [Matomo web analytics](https://matomo.org/). We'll be making a Docker "swarm-mode" `compose.yml` file. Here's an overview of the options you'd have to package Matomo:
2021-07-24 20:23:02 +00:00
2022-02-03 16:42:31 +00:00
- **Tired**: Write your own image and compose file from scratch
- **Wired**: Use someone else's image (& maybe compose file)
- **Inspired**: Upstream image, someone else's compose file
- **On fire**: Upstream image, Upstream compose file
2021-05-31 20:01:25 +00:00
2022-02-03 16:42:31 +00:00
Luckily, 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. That typically also means "not for production" but we can still use it as a solid base.
2021-07-24 20:23:02 +00:00
First, let's create a directory with the files we need:
```
abra recipe new matomo
2022-02-03 16:42:31 +00:00
cd ~/.abra/recipes/matomo
2021-07-24 20:23:02 +00:00
```
Then, let's download and edit the `docker-compose.yml` file:
2021-05-31 20:01:25 +00:00
```
mkdir matomo && cd matomo
wget https://raw.githubusercontent.com/matomo-org/docker/master/.examples/apache/docker-compose.yml -O compose.yml
```
2022-02-03 16:42:31 +00:00
Open the `compose.yml` in your favourite editor and have a gander 🦢. There are a few things we're looking for, but some immediate changes could be:
2021-05-31 20:01:25 +00:00
1. Let's bump the version to `3.8`, to make sure we can use all the latest swarm coolness
2022-02-03 16:42:31 +00:00
2. We load environment variables separately via [`abra`](/abra/), so we'll strip out `env_file`
3. 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. The developers have been nice enough to suggest `logs` and `config` volumes instead, which is a decent start
2021-05-31 20:01:25 +00:00
4. 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.
5. 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.
6. Lastly, we want to use `deploy.labels` and remove the `ports:` definition, to tell Traefik to forward requests to Matomo based on hostname and generate an SSL certificate.
The resulting `compose.yml` is available [here](https://git.autonomic.zone/coop-cloud/matomo/src/branch/main/compose.yml).
2021-07-24 20:23:02 +00:00
!!! note "Running Co-op Cloud server required!"
2022-02-03 16:42:31 +00:00
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 operators tutorial](/operators/tutorial) if you need help setting one up.
2021-07-24 20:23:02 +00:00
Now, we're ready to create a testing instance of Matomo:
2021-05-31 20:01:25 +00:00
```
2021-07-24 20:23:02 +00:00
abra app new matomo --secrets \
--domain matomo.swarm.example.com \
2022-02-03 16:42:31 +00:00
--server swarm.example.com
2021-09-30 13:15:44 +00:00
```
2021-07-24 20:23:02 +00:00
2022-02-03 16:42:31 +00:00
Depending on whether you defined any extra environment variables, we didn't so
far, in this example, you might want to run `abra app config swarm.example.com`
to check the configuration.
2021-05-31 20:01:25 +00:00
2021-07-24 20:23:02 +00:00
Otherwise, or once you've done that, go ahead and deploy the app:
2021-05-31 20:01:25 +00:00
2021-07-24 20:23:02 +00:00
```
2022-02-03 16:42:31 +00:00
abra app deploy swarm.example.com
2021-05-31 20:01:25 +00:00
```
2022-02-03 16:42:31 +00:00
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`](https://git.autonomic.zone/coop-cloud/mediawiki) for examples of both).
2022-01-26 10:47:44 +00:00
2022-02-03 16:42:31 +00:00
Congrats, you've packaged your first recipe! You've probably got more questions, check out the [maintainers handbook](/maintainers/handbook)!