Compare commits
1 Commits
main
...
push-yypzs
| Author | SHA1 | Date | |
|---|---|---|---|
| 8d666b06c4 |
@ -6,9 +6,9 @@ title: Hack
|
||||
|
||||
Welcome to Hacking the Planet with `abra`! We're looking forward to see what you come up. If you have any questions, don't hesitate to ask 💖 However, please keep in mind that if any of your changes seems a bit controversial, it's probably best to come have a chat first to avoid heartache.
|
||||
|
||||
In general, we're into the idea of "Optimistic Merging" (instead of "Pessimistic Merging") based on our understanding of [C4](https://hintjens.gitbooks.io/social-architecture/content/chapter4.html) (described further down under "Development Process" and also [in this blog post](http://hintjens.com/blog:106)).
|
||||
In general, we're into the idea of "Optimistic Merging" (instead of "Pessimistic Merging" based on our understanding of [C4](https://hintjens.gitbooks.io/social-architecture/content/chapter4.html) (described further down under "Development Process" and also [in this blog post](http://hintjens.com/blog:106)).
|
||||
|
||||
In other words, we're happy to grant contributors "the commit bit" (read/write permissions on our shared Git repositories) more or less as soon as you start to submit changes, write recipes, organise or in general, help out in the project. You don't have to prove anything, we can work and learn together! Mistakes are allowed and there are no "stupid questions".
|
||||
In other words, we're happy to give you, as contributor, "the commit bit" (read/write permissions on the Git repositories) more or less as soon as you start to submit changes, write recipes, organise or in general, help out in the project. You don't have to prove anything, we can work and learn together! Mistakes are allowed and there are no "stupid questions".
|
||||
|
||||
We maintain a "team" called "Co-operators" on our 2 main repositories:
|
||||
|
||||
@ -118,9 +118,6 @@ Once you're in, you can run the following:
|
||||
```
|
||||
sudo -su abra
|
||||
cd
|
||||
tmux ls # if there is a session, run: tmux attach
|
||||
# this way, we don't crash into each other
|
||||
# when we're running tests
|
||||
./run-ci-int
|
||||
```
|
||||
|
||||
@ -182,45 +179,31 @@ For some tests an actual server is needed, where apps can be deployed. You can e
|
||||
|
||||
##### Remote swarm
|
||||
|
||||
!!! warning
|
||||
|
||||
Right now, the test suite will check for a local swarm, see [abra/#769](https://git.coopcloud.tech/toolshed/abra/issues/769)
|
||||
|
||||
```
|
||||
export TEST_SERVER="test.example.com"
|
||||
export ABRA_DIR="$HOME/.abra_test"
|
||||
```
|
||||
|
||||
There should also be a DNS A record for `*.test.example.com` which points to the same server so that the test suite can deploy apps freely. The test suite does not deploy Traefik for you.
|
||||
`ABRA_TEST_DOMAIN` should also have a DNS A record for `*.test.example.com` which points to the same server so that the test suite can deploy apps freely. The test suite does not deploy Traefik for you.
|
||||
|
||||
##### Local swarm
|
||||
|
||||
!!! note
|
||||
|
||||
This is currently necessary even if you only want to run tests which don't need a server
|
||||
|
||||
When running the test suite locally you need a running docker swarm setup:
|
||||
When running the test suite localy you need a running docker swarm setup:
|
||||
|
||||
```
|
||||
docker swarm init
|
||||
docker network create -d overlay proxy
|
||||
```
|
||||
|
||||
To use the local swarm set the following env var:
|
||||
To use the local swarm set the foloowing env var:
|
||||
|
||||
```
|
||||
export TEST_SERVER=default
|
||||
export ABRA_DIR="$HOME/.abra_test"
|
||||
```
|
||||
|
||||
Make sure that the user running the tests can access the docker socket e.g. by adding it to the `docker` group (security considerations apply).
|
||||
|
||||
### Run tests
|
||||
|
||||
!!! note
|
||||
|
||||
You need to remember to compile your current version of `abra` via `make` before running the tests. See [abra/#770](https://git.coopcloud.tech/toolshed/abra/issues/770)
|
||||
|
||||
Now you can run the whole test suite:
|
||||
|
||||
```
|
||||
@ -333,25 +316,6 @@ It's also possible to translate using [`poedit`](https://poedit.net). Weblate is
|
||||
|
||||
All translation files are located in [`pkg/i18n/locales`](https://git.coopcloud.tech/toolshed/abra/src/branch/main/pkg/i18n/locales). Once translations are updated in weblate, they will be incorporated into the next release of `abra` automatically.
|
||||
|
||||
In general, the workflow for translators is:
|
||||
|
||||
- Code freeze announced for `abra` before release. Strings are not updated by developers and merge conflicts are avoided.
|
||||
- Translation work proceeds on [`translate.coopcloud.tech/projects/co-op-cloud/abra`](https://translate.coopcloud.tech/projects/co-op-cloud/abra/)
|
||||
- Translators ensure that the latest translation changes are synchronised to the `abra` git repository via [the settings](https://translate.coopcloud.tech/projects/co-op-cloud/abra/#repository)
|
||||
- Translators and developers will [install `abra` locally](/abra/hack/#super-quick-start-ubuntu-server) and test the latest changes
|
||||
- If all is well, we can release `abra`
|
||||
|
||||
### Updating `abradev`
|
||||
|
||||
If you followed the [Super quick-start instructions](/abra/hack/#super-quick-start-ubuntu-server) to install `abra`, then these are the instructions you need to update your local `abra` to get the latest changes from Weblate. Make sure to check that the latest Weblate changes are synchronised with the `abra` repository.
|
||||
|
||||
```
|
||||
cd
|
||||
cd abra
|
||||
git pull origin main
|
||||
make build
|
||||
```
|
||||
|
||||
### End-user workflow
|
||||
|
||||
You simply export the `LANG` env var to match your desired translation.
|
||||
@ -437,21 +401,15 @@ For developers, while using this `-beta` format, the `y` part is the "major" ver
|
||||
- Commit that change (e.g. `git commit -m 'chore: publish next tag x.y.z-beta'`)
|
||||
- Make a new tag (e.g. `git tag -a x.y.z-beta`)
|
||||
- Push the new tag (e.g. `git push && git push --tags`)
|
||||
- Wait until the build finishes successfully on [build.coopcloud.tech](https://build.coopcloud.tech/toolshed/abra)
|
||||
- Set your `GITEA_TOKEN` in your `.envrc` and run `make release` to release `abra`
|
||||
- Wait until the build finishes on [build.coopcloud.tech](https://build.coopcloud.tech/toolshed/abra)
|
||||
- Deploy the new installer script (e.g. `cd ./scripts/installer && make`)
|
||||
- Clean up the changelog on the [releases
|
||||
page](https://git.coopcloud.tech/toolshed/abra/releases) so it includes most
|
||||
relevant changes. [See below](/abra/hack/#release-notes-text) for the
|
||||
announcement text that needs to be inserted above the generated changelog.
|
||||
You can use something like `git shortlog -e -s -n 0.XX.0-beta..HEAD` to get
|
||||
the list of authors.
|
||||
- Make sure there is [a migration guide](/abra/upgrade/#migration-guides)
|
||||
written in the docs (if necessary)
|
||||
- Clean up the changelog on the releases page so it includes most relevant
|
||||
changes. See below for the announcement text that needs to be inserted above
|
||||
the generated changelog. You can use something like `git shortlog -e -s -n
|
||||
0.11.0-beta..HEAD` to get the list of authors.
|
||||
- Make sure there is a migration guide written in the docs (if necessary)
|
||||
- Check the release worked, (e.g. `abra upgrade; abra -v`)
|
||||
- Share [the standard announcement](/abra/hack/#general-announcement-text) on
|
||||
our General chat and [fedi account](https://social.coop/@coopcloud)
|
||||
- Run away!
|
||||
- Share the announcement on our General chat and fedi account:
|
||||
|
||||
#### Release notes text
|
||||
|
||||
@ -506,10 +464,6 @@ We maintain a fork of [docker-cli](https://git.coopcloud.tech/toolshed/docker-cl
|
||||
|
||||
A number of modules in [pkg/upstream](https://git.coopcloud.tech/toolshed/abra/src/branch/main/pkg/upstream) are copy/pasta'd from the upstream [docker/docker/client](https://pkg.go.dev/github.com/docker/docker/client). We had to do this because upstream are not exposing their API as public.
|
||||
|
||||
### `spf13/cobra`
|
||||
|
||||
Our command library doesn't support `i18n` so we need to implement a work-around specifically for translating the `--help` command. See [`spf13/cobra#2359`](https://github.com/spf13/cobra/issues/2359) for more.
|
||||
|
||||
### `github.com/schultz-is/passgen`
|
||||
|
||||
Due to [`toolshed/organising#358`](https://git.coopcloud.tech/toolshed/organising/issues/358).
|
||||
|
||||
@ -8,6 +8,8 @@ title: Abra
|
||||
[](https://goreportcard.com/report/git.coopcloud.tech/toolshed/abra)
|
||||
[](https://pkg.go.dev/coopcloud.tech/abra)
|
||||
|
||||
`abra` is the flagship client & command-line for Co-op Cloud. It has been developed specifically for the purpose of making the day-to-day operations of operators and maintainers pleasant & convenient. It is libre software, written in Go and maintained and extended by the community :heart:
|
||||
|
||||
`abra` is the flagship client & command-line tool for Co-op Cloud. It has been developed specifically for the purpose of making the day-to-day operations of [operators](https://docs.coopcloud.tech/operators/) and [maintainers](https://docs.coopcloud.tech/maintainers/) pleasant & convenient. It is libre software, written in [Go](https://go.dev) and maintained and extended by the community 💖
|
||||
|
||||
Once you've got `abra` installed, you can start your own Co-op Cloud deployment.
|
||||
|
||||
@ -1,55 +0,0 @@
|
||||
---
|
||||
title: Swarm mode almanac
|
||||
---
|
||||
|
||||
> !!! warning "This page is a Work In Progress :tm:"
|
||||
A page to understand WTF is going on with [Swarm mode](https://docs.docker.com/engine/swarm/key-concepts/) and how we rely on it, how we might not rely on it and other related threads. Please add to this page as you see fit! If we can establish some shared understanding of what is going on under the hood, we can come up with a collective solution which meets everyones needs.
|
||||
|
||||
## Support matrix
|
||||
|
||||
In practice, this is what we currently rely on Swarm mode for.
|
||||
|
||||
| Feature | Explanation |
|
||||
| ----------- | ----------- |
|
||||
| Encrypted secrets | When you run `abra secret generate`, it uses something like `printf foo | docker secret create foo -` under the hood. This feature only works if you have first run `docker swarm join`. Swarm mode [securely transports and stores your secret encrypted on the server](https://docs.docker.com/engine/swarm/secrets/#how-docker-manages-secrets). `docker compose` does not support encrypting or storing secrets because it only runs client-side. |
|
||||
| Template driver | If you use `template_driver: golang` in your `compose.yml` to insert secrets or environment variables into your configs, then you are using a template driver. This feature has almost 0 documentation and does not appear to be supported by [the actual Compose Spec](https://github.com/compose-spec/compose-spec/blob/main/08-configs.md) and is actually completely blocked by `docker compose` ([source](https://github.com/docker/compose/blob/f9828dfab909e9dd0dd489a49088c8619ec2ca7e/pkg/compose/create.go#L1095)). Several recipes use this feature and it seems quite crucial for our usage. |
|
||||
| Stacks | Firstly, [a service](https://docs.docker.com/engine/swarm/how-swarm-mode-works/services/) is key concept here. A stack is then a shared namespace of services with networks, volumes, configs etc. The concept of a stack is a [unique](https://docs.docker.com/engine/swarm/stack-deploy/) to Swarm mode. Any replacement for Swarm mode would have to implement this kind of namespacing feature for backwards compatibility purposes. See [`psviderski/uncloud#94`](https://github.com/psviderski/uncloud/discussions/94) for more. |
|
||||
| Orchestration | When you run `abra app deploy`, we're running a slightly customised `docker stack deploy` under the hood. Swarm mode is supposed to automagically handle zero downtime updates and rollbacks if things fail. However, we're seeing [the limitations of this approach](/abra/swarm/#limitations). |
|
||||
|
||||
## Unsupport matrix
|
||||
|
||||
| Feature | Explanation |
|
||||
| ----------- | ----------- |
|
||||
| Multi-node | It is possible but it doesn't seem like anyone in our community is really doing this. We believe the majority of Co-op Cloud installs are single node. There is also a lack of [CSI](https://github.com/olljanat/csi-plugins-for-docker-swarm?tab=readme-ov-file) support for coordinating storage across multiple hosts when using Swarm mode. This means we kind of throw out [the majority](https://docs.docker.com/engine/swarm/#feature-highlights) of the features of Swarm mode. |
|
||||
|
||||
## Limitations
|
||||
|
||||
* Swarm mode is still eerily underdeveloped and lacking features as a system. There are still some lurking network and stability bugs which are common. We're grateful for the undercover live reporting from people in-the-know adjacent to our network below. There are even folx inside Docker who are apparently calling it abandonware ([source](https://git.coopcloud.tech/toolshed/organising/issues/682#issuecomment-30235)). All this does not really put us at ease.
|
||||
|
||||
!!! note "Docker whiskey leaks"
|
||||
|
||||
> https://www.mirantis.com/blog/mirantis-guarantees-long-term-support-for-swarm/
|
||||
>
|
||||
> Mirantis' relationship with "swarm" is very confusing! my understanding is that there are people (or one person? lol) at mirantis who do some work on the orchestration engine that is "docker swarm," but only to the extent that it supports mirantis' platform. i don't believe there's any active feature development beyond that. you're right that it's a misleading headline -- it sounds to me that they're just saying that they'll continue swarm support in their v3 kubernetes platform, not that they're committed to developing swarm as an orchestration system.
|
||||
>
|
||||
> Way back when (i guess in 2019? before my time!), docker sold off its enterprise platform which was called "swarm" to mirantis, so that's still a product that mirantis has and has developed in their way, but it's not the open-source swarm(kit) that's part of the docker cli. this is a good quick explanation: https://forums.docker.com/t/docker-swarmkit-and-the-mirantis-deal-not-docker-swarm/88886
|
||||
|
||||
* The orchestration features of Swarm mode are opaque, causing failed deployments to be difficult to understand. This can cause a litany of a issues. For example, in the case where your database has been migrated and a rollback of your failing app doesn't support the new schema. This is being discussed extensively on [`organising#682`](https://git.coopcloud.tech/toolshed/organising/issues/682).
|
||||
|
||||
## Potential alternatives
|
||||
|
||||
* [`uncloud.run`](https://github.com/psviderski/uncloud): The Uncloud folks are creating a very different system. Something beyond compose but not k8s and not Swarm. This means they have to implement a lot of features of the orchestration from scratch. However, they're going for a nice approach: a straight-forward imperative deployment model (supports `depends_on` for predictable ordering during deployments). They're choosing which parts of the Compose Spec they implement and it's noteworthy that they [don't implement secrets yet](https://github.com/psviderski/uncloud/issues/75). See the [Compose support matrix](https://uncloud.run/docs/compose-file-reference/support-matrix) for more. They are however very focused on multi-node functionality. It's a system to [keep an eye on](https://github.com/psviderski/uncloud/milestone/1) with the hope that we can use some part of it in the future. Lines of communication [have been opened](https://github.com/psviderski/uncloud/discussions/255).
|
||||
|
||||
* [`docker compose`](https://github.com/docker/compose): Plain old `docker compose`. A more elegant weapon for a more civilised age. It is however missing features we need such as encrypted secrets and `template_driver` support. There may be [more things missing](https://github.com/docker/compose/issues/11867). They are developing a promising [SDK](https://docs.docker.com/compose/compose-sdk/) exposes a public API for handling various operations. This would need some serious investigation and most likely some custom solutions for the features we're missing.
|
||||
|
||||
## What we need
|
||||
|
||||
* Something that is backwards compatible with our existing recipe configuration commons and the current deployments. We can't re-invent the wheel because we all rely on this system. So, we need to look towards incremental improvements or changes which are backwards compatible. We can always agree to change the config commons or some shared practices but then we need to establish a clear agreement with decision making. This is the social part.
|
||||
|
||||
* Some way of conveniently using secrets when deploying services. This method should easily support working in a team which doesn't stray too far from our established Git Ops workflow of sharing `$ABRA_DIR`. They don't need to be encrypted and stored on the server (removing the need for Swarm mode handling) as long as they're mounted as secrets in the usual `/run/secret/<name>` manner at runtime.
|
||||
|
||||
* Template driver support so we can template values into our configurations. This is used in enough recipes to warrant continued support.
|
||||
|
||||
* A way to namespace services into a deployment, aka a "Docker Stack". This would appear to be a minor implementation detail after all is said and done. It's services all the way down and they have some linked networks/configs/volumes/etc. and a shared naming convention.
|
||||
|
||||
* Some way to achieve [Fearless YunoHost-esque Upgrades](https://git.coopcloud.tech/toolshed/organising/issues/682#issuecomment-29302). In other words, some predictable way to deploy / upgrade / rollback and some way to intervene when things go wrong. It should be easy to understand for everyone and would enable real stability for operators. I think we want some sort of anti-orchestration implementation which is super simple.
|
||||
@ -53,15 +53,6 @@ And test things work.
|
||||
|
||||
> General release notes are [here](https://git.coopcloud.tech/toolshed/abra/releases/)
|
||||
|
||||
### `0.12.x-beta` -> `0.13.x-beta`
|
||||
|
||||
* `abra recipe sync` went away. You now only need to run `upgrade`/`release`.
|
||||
See [`#682`](https://git.coopcloud.tech/toolshed/abra/issues/682) for the
|
||||
design details and
|
||||
[here](/maintainers/handbook/#upstream-released-a-new-version-how-do-i-upgrade-the-recipe)
|
||||
for the revised documentation. Thanks to `@iexos` for getting this out the
|
||||
door!
|
||||
|
||||
### `0.11.x-beta` -> `0.12.x-beta`
|
||||
|
||||
* `kadabra` has been archived and is no longer published alongside `abra`
|
||||
|
||||
@ -35,5 +35,3 @@ Here is some invitation boilerplate which you can use:
|
||||
> We take notes and doodle on [this collaboratively editable pad](https://pad.autonomic.zone/VtyrLUl9RWaJGgEDrncQUw?view). If you don't have time to attend, feel free to drop your questions and some contact details also, so we can get in touch. This is only the first Kite Flying Hour in a recurring series of Kite Flying Hours.
|
||||
>
|
||||
> Hope to see you there! ☁️ 🌞 🖥️
|
||||
|
||||
To work around Hedgedoc length limits, [we keep past content from the kite-flying pad here](./kite-flying-pad-archive).
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -10,7 +10,7 @@ Welcome to the organisers guide! Organisers are folks who focus on the social wo
|
||||
|
||||
One-stop shop for all you need to know to organise in the community :sparkles:
|
||||
|
||||
[Read Handbook](/federation/handbook){ .md-button .md-button--primary }
|
||||
[Read Handbook](/organisers/handbook){ .md-button .md-button--primary }
|
||||
|
||||
- __Say Hello First__
|
||||
|
||||
|
||||
@ -1,29 +0,0 @@
|
||||
---
|
||||
title: "Resolution 038: Merri-bek Tech joins Co-op Cloud Federation"
|
||||
---
|
||||
|
||||
- Topic: Merri-bek Tech joins Coopcloud
|
||||
- Date: 2026-03-02
|
||||
- Deadline: 2026-03-16
|
||||
- Size: Large
|
||||
|
||||
### Summary
|
||||
|
||||
Merri-bek Tech is working towards neighbourhood-first, community controlled web services, building infrastructure using the Co-op Cloud stack. Merri-bek Tech expects to pay membership dues.
|
||||
|
||||
### Details
|
||||
|
||||
Merri-bek Tech
|
||||
|
||||
- currently depends on Traefik for neighbourhood-distributed nodes.
|
||||
- have developed and are maintaining Kiwix Co-op Cloud recipe for deploying Wikipedia across neighbourhood nodes
|
||||
- plans to use and contribute to maintenance, of additional components of Co-op Cloud stack as needed for subsequent phases of the project roadmap: neighbhourhood based email service, web hosting and decentralized social media.
|
||||
|
||||
@jade:merri-bek.chat is an active member of the Co-op Cloud community.
|
||||
The group is based in Merri-bek, in the inner Northern suburbs of Naarm (Melbourne), Australia
|
||||
|
||||
[Merri-bek Tech Inc.] is legally an incorporated association in Australia, which is a legal entity used for democratic clubs and societies. It is not intended to be a worker co-operative, it is a volunteer commons project, but it shares the mutuality goals of cooperatives. Full details are at [merri-bek.tech](https://merri-bek.tech).
|
||||
|
||||
The project that Merri-bek Tech is running to promote Neighbourhood-First Software in Merri-bek and other regions, is detailed at [lores.tech](https://lores.tech).
|
||||
|
||||
@ammaratef45 from RTM is honored to vouch
|
||||
@ -612,6 +612,23 @@ Add the `# generate=false` comment
|
||||
SECRET_JWT_SECRET_VERSION=v1 # generate=false
|
||||
```
|
||||
|
||||
## How do I specify the charset for a specific secret generation
|
||||
|
||||
!!! warning "Watch out for old versions of `abra` 🚧"
|
||||
|
||||
This feature is only available in the >= 0.10.x series of `abra`.
|
||||
|
||||
```
|
||||
SECRET_JWT_SECRET_VERSION=v1 # charset=default,special
|
||||
```
|
||||
|
||||
Options are:
|
||||
|
||||
* `special`: [source](https://github.com/decentral1se/passgen/blob/8404cb922dea92efa8c3514f0ec8c37ce12a880f/const.go#L22C29-L22C43)
|
||||
* `safespecial`: [source](https://git.coopcloud.tech/toolshed/abra/src/commit/6abaf7a094df1a96599af2c4cbae1769821ad17c/pkg/secret/secret.go#L182)
|
||||
* `default,special`: mix of `default` and `special`
|
||||
* `default,safespecial`: mix of `default` and `safespecial`
|
||||
|
||||
## How do I change secret generation length?
|
||||
|
||||
It is possible to tell `abra` which length it should generate secrets with from your recipe config.
|
||||
@ -633,13 +650,6 @@ of passwords which admins have to type out in database shells.
|
||||
|
||||
## How do I change secret generation characters?
|
||||
|
||||
!!! warning "Watch out for old versions of `abra` 🚧"
|
||||
|
||||
This feature is only available in the >= 0.10.x series of `abra`.
|
||||
The generation of `hex` secrets is only available in the >= 0.12.x series of `abra`.
|
||||
The generation of `bytes` secrets is only available in the >= 0.13.x series of `abra`.
|
||||
|
||||
|
||||
It is also possible to tell `abra` which characters it should use to generate secrets with from your recipe config.
|
||||
|
||||
You do this by adding an additional modifier in the inline comment on the secret definition in the `.env.sample` / `.env` file.
|
||||
@ -660,52 +670,10 @@ The possible Values are:
|
||||
| `default,special` | `abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ23456789!@#$%^&*_-+=` | Uses uppercase letters, lowercase letters and numbers and special characters |
|
||||
| `default,safespecial` | `abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ23456789!@#%^&*_-+=` | Uses uppercase letters, lowercase letters and numbers and console safe special characters |
|
||||
| `default` | `abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ23456789` | Uses uppercase letters, lowercase letters and numbers |
|
||||
| `hex` | `0123456789abcdef` | Uses only hexadecimal characters (0-9, a-f) |
|
||||
| `bytes` | N/A (generates random bytes) | Generates random bytes instead of character-based passwords (requires `length` modifier, automatically uses `encoding=base64`) |
|
||||
| any other value or not setting one will be treated as `default` | `abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ23456789` | Uses uppercase letters, lowercase letters and numbers |
|
||||
|
||||
The setting does only apply when you also set a length modifier to the secret (documented [here](/maintainers/handbook/#how-do-i-change-secret-generation-length)), so it is not applicable for the "easy to remember word" style generator that used when you don't set a length.
|
||||
|
||||
## How do I encode generated secrets?
|
||||
|
||||
!!! warning "Watch out for old versions of `abra` 🚧"
|
||||
|
||||
This feature is only available in the >= 0.13.x series of `abra`.
|
||||
|
||||
You can tell `abra` to encode generated secrets using the `encoding` modifier in the inline comment on the secret definition in the `.env.sample` / `.env` file.
|
||||
|
||||
Here is an example:
|
||||
|
||||
```bash
|
||||
SECRET_API_KEY_VERSION=v1 # length=32 encoding=base64
|
||||
```
|
||||
|
||||
This will generate a 32-character secret and then base64-encode it before storing.
|
||||
|
||||
Currently supported encoding options:
|
||||
|
||||
- `base64`: Base64-encodes the generated secret value
|
||||
|
||||
**Note:** When using `charset=bytes`, the encoding automatically defaults to `base64` even if not explicitly specified, as raw binary data needs to be encoded for safe storage.
|
||||
|
||||
## How do I add a prefix to generated secrets?
|
||||
|
||||
!!! warning "Watch out for old versions of `abra` 🚧"
|
||||
|
||||
This feature is only available in the >= 0.13.x series of `abra`.
|
||||
|
||||
You can tell `abra` to add a prefix to generated secrets using the `prefix` modifier in the inline comment on the secret definition in the `.env.sample` / `.env` file.
|
||||
|
||||
Here is an example:
|
||||
|
||||
```bash
|
||||
SECRET_APP_KEY_VERSION=v1 # length=32 charset=bytes prefix=base64:
|
||||
```
|
||||
|
||||
This will generate a 32-byte random key, base64-encode it, and prefix it with `base64:`. This is useful for applications like Laravel that expect secrets in a specific format.
|
||||
|
||||
The prefix is applied after any encoding transformations.
|
||||
|
||||
## How do I configure backup/restore?
|
||||
|
||||
From the perspective of the recipe maintainer, backup/restore is just more
|
||||
|
||||
@ -521,9 +521,7 @@ Yes, as of [`#585`](https://git.coopcloud.tech/toolshed/abra/pulls/585), this is
|
||||
## Running an offline coop-cloud server
|
||||
|
||||
You may want to run a coop-cloud directly on your device (or in a VM or machine on your LAN), whether that's for testing a recipe or to run coop-cloud apps outside of the cloud ;-)
|
||||
|
||||
In that case you might set up your server with `abra add server --local` like you would do it [running abra server side](#running-abra-server-side) (without a specific server name).
|
||||
Then you could simply add some names to `/etc/hosts` (e.g `127.0.0.1 myapp.localhost`, `127.0.0.1 coopcloud.local`, `127.0.0.1 *.coopcloud.local`), or configure them on a local DNS server - which means `traefik` won't be able to use `letsencrypt` to generate and verify SSL certificates. Here's what you can do instead:
|
||||
In that case you might simply add some names to `/etc/hosts` (e.g `127.0.0.1 myapp.localhost`), or configure them on a local DNS server - which means `traefik` won't be able to use `letsencrypt` to generate and verify SSL certificates. Here's what you can do instead:
|
||||
1. In your traefik .env file, edit/uncomment the following lines:
|
||||
```
|
||||
LETS_ENCRYPT_ENV=staging
|
||||
@ -532,8 +530,7 @@ SECRET_WILDCARD_CERT_VERSION=v1
|
||||
SECRET_WILDCARD_KEY_VERSION=v1
|
||||
COMPOSE_FILE="$COMPOSE_FILE:compose.wildcard.yml"
|
||||
```
|
||||
2. Generate a self-signed certificate using the [command listed here](https://letsencrypt.org/docs/certificates-for-localhost/#making-and-trusting-your-own-certificates). Unless using `localhost` you may want to edit that where it appears in the command, and/or add multiple (sub)domains to the certificate e.g: `subjectAltName=DNS:localhost,DNS:myapp.localhost`. You can also use wildcard-subdomains if you want to be more flexible later one, which apps to deploy: `subjectAltName=DNS:coopcloud.local,DNS:*.coopcloud.local`.
|
||||
|
||||
2. Generate a self-signed certificate using the [command listed here](https://letsencrypt.org/docs/certificates-for-localhost/#making-and-trusting-your-own-certificates). Unless using `localhost` you may want to edit that where it appears in the command, and/or add multiple (sub)domains to the certificate e.g: `subjectAltName=DNS:localhost,DNS:myapp.localhost`
|
||||
3. Run these commands:
|
||||
```
|
||||
abra app secret insert localhost ssl_cert v1 localhost.crt -f
|
||||
|
||||
@ -84,7 +84,6 @@ nav:
|
||||
- federation/index.md
|
||||
- federation/handbook.md
|
||||
- federation/organisers.md
|
||||
- federation/kite-flying-pad-archive.md
|
||||
- "Bylaws": federation/bylaws.md
|
||||
- "Finance": federation/finance.md
|
||||
- "Membership": federation/membership.md
|
||||
@ -138,7 +137,6 @@ nav:
|
||||
- federation/resolutions/index.md
|
||||
- federation/resolutions/in-progress/035.md
|
||||
- federation/resolutions/in-progress/037.md
|
||||
- federation/resolutions/in-progress/038.md
|
||||
- "Minutes":
|
||||
- federation/minutes/index.md
|
||||
- "Recently":
|
||||
@ -168,7 +166,6 @@ nav:
|
||||
- "Hack": abra/hack.md
|
||||
- "Troubleshoot": abra/trouble.md
|
||||
- "Cheat Sheet": abra/cheat-sheet.md
|
||||
- "Swarm mode almanac": abra/swarm.md
|
||||
- "Specifications":
|
||||
- specs/index.md
|
||||
- "Backups":
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
mkdocs~=1.6.1
|
||||
|
||||
mkdocs-material==9.6.20
|
||||
mkdocs-material==9.5.49
|
||||
mkdocs-material-extensions==1.3.1
|
||||
mkdocs-awesome-pages-plugin==2.10.1
|
||||
pygments==2.19.1
|
||||
|
||||
Reference in New Issue
Block a user