forked from toolshed/docs.coopcloud.tech
Compare commits
50 Commits
Author | SHA1 | Date | |
---|---|---|---|
e31f5ece7f | |||
2bc61ebb36
|
|||
d3e78c5fb4
|
|||
1a4186210a
|
|||
5f8633432d
|
|||
4869031a10
|
|||
e3a178e5fc
|
|||
82ae5d044d
|
|||
833317d67c
|
|||
7db77d3199
|
|||
18c77fbd00
|
|||
307ddf104a
|
|||
1e481840da
|
|||
8ee454a6c2
|
|||
5235b796e4
|
|||
70ca00d2f4
|
|||
3c580c6a19
|
|||
bd9930fb46
|
|||
b69dbd89bb
|
|||
839ce6f279
|
|||
313069851c | |||
a133b5ce98
|
|||
574f6fa368
|
|||
4282777b0b
|
|||
ec369d7fb9
|
|||
7e27c6cd11
|
|||
433739bf98
|
|||
e3d14a7084
|
|||
bf193f5d1c
|
|||
6e81f46078 | |||
5d90eac73b | |||
52a3cd9520 | |||
13c5ae9b7b
|
|||
eac97bc08b
|
|||
e9861c5d55
|
|||
2f7d23b208
|
|||
fd19a44a16
|
|||
4d96899fce
|
|||
cfbc3a3438
|
|||
2813257e30
|
|||
7f2c1df18e | |||
1e4dd4658d | |||
0bb023f9ed | |||
4783299c4e | |||
7d0ec72bf6 | |||
506578753b | |||
11764163d1 | |||
c648f67cef | |||
50b5212d8c | |||
2ea8e5c1ab |
21
.drone.yml
21
.drone.yml
@ -5,10 +5,10 @@ steps:
|
||||
- name: build static
|
||||
image: plugins/docker
|
||||
settings:
|
||||
username: 3wordchant
|
||||
username: abra-bot
|
||||
password:
|
||||
from_secret: git_coopcloud_tech_token_3wc
|
||||
repo: git.coopcloud.tech/coop-cloud/docs.coopcloud.tech
|
||||
from_secret: git_coopcloud_tech_token_abra_bot
|
||||
repo: git.coopcloud.tech/toolshed/docs.coopcloud.tech
|
||||
tags: latest
|
||||
registry: git.coopcloud.tech
|
||||
|
||||
@ -21,21 +21,6 @@ steps:
|
||||
from_secret: drone_ssh_swarm-0_coopcloud_tech
|
||||
depends_on:
|
||||
- build static
|
||||
|
||||
- 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: autonobot_rocketchat_access_token
|
||||
depends_on:
|
||||
- build static
|
||||
- deployment
|
||||
when:
|
||||
status:
|
||||
- failure
|
||||
trigger:
|
||||
branch:
|
||||
- main
|
||||
|
@ -1,4 +1,4 @@
|
||||
FROM squidfunk/mkdocs-material:9.5.7
|
||||
FROM squidfunk/mkdocs-material:9.5.49
|
||||
|
||||
EXPOSE 8000
|
||||
|
||||
|
@ -1,6 +1,6 @@
|
||||
# docs.coopcloud.tech :open_book:
|
||||
|
||||
[](https://build.coopcloud.tech/coop-cloud/docs.coopcloud.tech)
|
||||
[](https://build.coopcloud.tech/toolshed/docs.coopcloud.tech)
|
||||
|
||||
View: [docs.coopcloud.tech](https://docs.coopcloud.tech)
|
||||
|
||||
|
@ -3,7 +3,7 @@ version: "3.8"
|
||||
|
||||
services:
|
||||
app:
|
||||
image: thecoopcloud/docs.coopcloud.tech:latest
|
||||
image: git.coopcloud.tech/toolshed/docs.coopcloud.tech:latest
|
||||
networks:
|
||||
- proxy
|
||||
healthcheck:
|
||||
|
@ -4,20 +4,24 @@ title: Hack
|
||||
|
||||
## Contributing
|
||||
|
||||
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 💖 If any of your
|
||||
changes seems a bit controversial, it's probably to come have a chat first to
|
||||
avoid heartache.
|
||||
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 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:
|
||||
|
||||
* [`git.coopcloud.tech/org/toolshed`](https://git.coopcloud.tech/org/toolshed/)
|
||||
* [`git.coopcloud.tech/org/coop-cloud`](https://git.coopcloud.tech/org/coop-cloud/)
|
||||
|
||||
This gives you read/write access to all the repositories of the organisation.
|
||||
|
||||
Any existing contributor can add you.
|
||||
|
||||
## Quick start
|
||||
|
||||
Get a fresh copy of the `abra` source code from [here](https://git.coopcloud.tech/coop-cloud/abra).
|
||||
Get a fresh copy of the `abra` source code from [here](https://git.coopcloud.tech/toolshed/abra).
|
||||
|
||||
Install [direnv](https://direnv.net), run `cp .envrc.sample .envrc`, then run `direnv allow` in this directory. Or you can run `go env -w GOPRIVATE=coopcloud.tech` but I'm not sure how persistent this is.
|
||||
|
||||
@ -28,9 +32,9 @@ Install [Go >= 1.16](https://golang.org/doc/install) and then:
|
||||
- `make test` will run tests
|
||||
- `make install-abra` will install abra to `$GOPATH/bin`
|
||||
- `make install-kadabra` will install kadabra to `$GOPATH/bin`
|
||||
- `go get <package>` and `go mod tidy` to add a new dependency
|
||||
- `go get <package>`, `go mod tidy` and `go mod vendor` to add a new dependency
|
||||
|
||||
Our [Drone CI configuration](https://git.coopcloud.tech/coop-cloud/abra/src/branch/main/.drone.yml) runs a number of checks on each pushed commit. See the [Makefile](https://git.coopcloud.tech/coop-cloud/abra/src/branch/main/Makefile) for more handy targets.
|
||||
Our [Drone CI configuration](https://git.coopcloud.tech/toolshed/abra/src/branch/main/.drone.yml) runs a number of checks on each pushed commit. See the [Makefile](https://git.coopcloud.tech/toolshed/abra/src/branch/main/Makefile) for more handy targets.
|
||||
|
||||
Please use the [conventional commit format](https://www.conventionalcommits.org/en/v1.0.0/) for your commits so we can automate our change log.
|
||||
|
||||
@ -56,17 +60,13 @@ go test ./pkg/recipe -v -run TestGetVersionLabelLocalDoesNotUseTimeoutLabel
|
||||
|
||||
### Running on the CI server
|
||||
|
||||
Based on
|
||||
[R020](https://docs.coopcloud.tech/federation/resolutions/passed/020/), we have
|
||||
automated running the integration test suite. Here's the TLDR;
|
||||
Based on [R020](https://docs.coopcloud.tech/federation/resolutions/passed/020/), we have automated running the integration test suite. Here's the TLDR;
|
||||
|
||||
* We have a donated CI server (tysm `@mirsal` 💝) standing at the ready,
|
||||
`int.coopcloud.tech`.
|
||||
* We run the entire integration suite nightly via our Drone CI/CD configuration [here](https://git.coopcloud.tech/coop-cloud/abra/src/branch/main/.drone.yml) (see "`name: integration test`" stanza)
|
||||
* Here is the script that is run on the remote server: [`run-ci-int`](https://git.coopcloud.tech/coop-cloud/abra/src/branch/main/scripts/tests/run-ci-int)
|
||||
* We have a donated CI server (tysm `@mirsal` 💝) standing at the ready, `int.coopcloud.tech`.
|
||||
* We run the entire integration suite nightly via our Drone CI/CD configuration [here](https://git.coopcloud.tech/toolshed/abra/src/branch/main/.drone.yml) (see "`name: integration test`" stanza)
|
||||
* Here is the script that is run on the remote server: [`run-ci-int`](https://git.coopcloud.tech/toolshed/abra/src/branch/main/scripts/tests/run-ci-int)
|
||||
|
||||
What follows is a listing of how this was achieved so that we can collectivise
|
||||
the maintenance.
|
||||
What follows is a listing of how this was achieved so that we can collectivise the maintenance.
|
||||
|
||||
On the server, we have:
|
||||
|
||||
@ -80,8 +80,8 @@ The drone configuration was wired up as follows:
|
||||
|
||||
* Generated a SSH key and put the public key part in `~/.ssh/authorize_keys`
|
||||
* Added that public key part as a "deploy key" in the abra repo (so we can do `ssh://` git remote pulls)
|
||||
* Added the private key part as a Drone secret which is available in build so that the build can SSH over to the server to run commands. That was done like so: `drone secret add --repository coop-cloud/abra --name abra_int_private_key --data @id_ed25519`
|
||||
* In order to specify a cron timing, you need to create it with the Drone CLI: `drone cron add "coop-cloud/abra" "integration" @daily --branch main`
|
||||
* Added the private key part as a Drone secret which is available in build so that the build can SSH over to the server to run commands. That was done like so: `drone secret add --repository toolshed/abra --name abra_int_private_key --data @id_ed25519`
|
||||
* In order to specify a cron timing, you need to create it with the Drone CLI: `drone cron add "toolshed/abra" "integration" @daily --branch main`
|
||||
|
||||
Please ask `@decentral1se` or on the Matrix channels for SSH access to the machine.
|
||||
|
||||
@ -89,17 +89,13 @@ Please ask `@decentral1se` or on the Matrix channels for SSH access to the machi
|
||||
|
||||
#### Install dependencies
|
||||
|
||||
We use [`bats`](https://bats-core.readthedocs.io/en/stable/) to run the tests.
|
||||
You can install the required dependencies with the following. You also need a
|
||||
working installation of Docker and Go >= 1.16 (not covered in this section).
|
||||
We use [`bats`](https://bats-core.readthedocs.io/en/stable/) to run the tests. You can install the required dependencies with the following. You also need a working installation of Docker and Go >= 1.16 (not covered in this section).
|
||||
|
||||
```
|
||||
apt install bats-file bats-assert bats-support jq make git
|
||||
```
|
||||
|
||||
Unfortunately, the latest `bats` version in Debian stable does not have the
|
||||
"filter tests by tags" feature, which is very handy for running a subset of the
|
||||
tests. For this, we need to install `bats` from source. It's easy.
|
||||
Unfortunately, the latest `bats` version in Debian stable does not have the "filter tests by tags" feature, which is very handy for running a subset of the tests. For this, we need to install `bats` from source. It's easy.
|
||||
|
||||
```
|
||||
apt purge -y bats
|
||||
@ -110,10 +106,7 @@ sudo ./install.sh /usr/local
|
||||
|
||||
#### Setup Test Server
|
||||
|
||||
For some tests an actual server is needed, where apps can be deployed. You can
|
||||
either use a local one or a remote test server. There is also a way to run or
|
||||
skip tests that require a remote server. This is covered below in the
|
||||
[filtering tests](#filter-tests_1) section.
|
||||
For some tests an actual server is needed, where apps can be deployed. You can either use a local one or a remote test server. There is also a way to run or skip tests that require a remote server. This is covered below in the [filtering tests](#filter-tests_1) section.
|
||||
|
||||
##### Remote swarm
|
||||
|
||||
@ -122,9 +115,7 @@ export ABRA_TEST_DOMAIN="test.example.com"
|
||||
export ABRA_DIR="$HOME/.abra_test"
|
||||
```
|
||||
|
||||
`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.
|
||||
`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
|
||||
|
||||
@ -153,13 +144,12 @@ bats -Tp tests/integration
|
||||
Or you can run a single test file:
|
||||
|
||||
```
|
||||
bats -Tp tests/integration/autocomplete.bats
|
||||
bats -Tp tests/integration/app_check.bats
|
||||
```
|
||||
|
||||
### Tagging tests
|
||||
|
||||
When a test actually deploys something, we tag it as "slow". When the test
|
||||
requires public DNS, we use "dns". There may be more tags we write more tests.
|
||||
When a test actually deploys something, we tag it as "slow". When the test requires public DNS, we use "dns". There may be more tags we write more tests.
|
||||
|
||||
```
|
||||
# bats test_tags=slow,dns
|
||||
@ -168,18 +158,14 @@ requires public DNS, we use "dns". There may be more tags we write more tests.
|
||||
}
|
||||
```
|
||||
|
||||
Then we can use [filters](#filter-tests) (see below) to pick out a subset of
|
||||
tests which do/do not use a live server. Feel free to come up with your own
|
||||
tags. See the `bats-core`
|
||||
[docs](https://bats-core.readthedocs.io/en/stable/writing-tests.html#tagging-tests)
|
||||
for more.
|
||||
Then we can use [filters](#filter-tests) (see below) to pick out a subset of tests which do/do not use a live server. Feel free to come up with your own tags. See the `bats-core` [docs](https://bats-core.readthedocs.io/en/stable/writing-tests.html#tagging-tests) for more.
|
||||
|
||||
### Filter tests
|
||||
|
||||
You can run a specific file.
|
||||
|
||||
```
|
||||
bats -Tp tests/integration/autocomplete.bats
|
||||
bats -Tp tests/integration/app_check.bats
|
||||
```
|
||||
|
||||
For example, if you want to check that all `abra recipe ...` tests remain working.
|
||||
@ -212,9 +198,7 @@ bats -Tp tests/integration --filter-status failed # re-run only failed
|
||||
|
||||
### Debug tests
|
||||
|
||||
If you're running into issues and want to debug stuff, you can pass `-x` to
|
||||
`bats` to trace all commands run in the test. You can add `echo '...' >&3`
|
||||
debug statements to your test to output stuff also.
|
||||
If you're running into issues and want to debug stuff, you can pass `-x` to `bats` to trace all commands run in the test. You can add `echo '...' >&3` debug statements to your test to output stuff also.
|
||||
|
||||
## Using the `abra` public API
|
||||
|
||||
@ -255,11 +239,11 @@ func main() {
|
||||
|
||||
Some tools that are making use of the API so far are:
|
||||
|
||||
* [`kadabra`](https://git.coopcloud.tech/coop-cloud/abra/src/branch/main/cmd/kadabra/main.go)
|
||||
* [`kadabra`](https://git.coopcloud.tech/toolshed/abra/src/branch/main/cmd/kadabra/main.go)
|
||||
|
||||
## Cross-compiling
|
||||
|
||||
If there's no official release for the architecture you use, you can cross-compile `abra` very easily. Clone the source code from [here](https://git.coopcloud.tech/coop-cloud/abra) and then:
|
||||
If there's no official release for the architecture you use, you can cross-compile `abra` very easily. Clone the source code from [here](https://git.coopcloud.tech/toolshed/abra) and then:
|
||||
|
||||
- enter the `abra` directory
|
||||
- run `git tag -l` to see the list of tags, choose the latest one
|
||||
@ -288,11 +272,11 @@ For developers, while using this `-beta` format, the `y` part is the "major" ver
|
||||
### Making a new release
|
||||
|
||||
- Run the [integration test suite](#integration-tests) and the unit tests (`make test`) (takes a while!)
|
||||
- Change `ABRA_VERSION` in [`scripts/installer/installer`](https://git.coopcloud.tech/coop-cloud/abra/src/branch/main/scripts/installer/installer) to match the new tag (use [semver](https://semver.org))
|
||||
- Change `ABRA_VERSION` in [`scripts/installer/installer`](https://git.coopcloud.tech/toolshed/abra/src/branch/main/scripts/installer/installer) to match the new tag (use [semver](https://semver.org))
|
||||
- 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 on [build.coopcloud.tech](https://build.coopcloud.tech/coop-cloud/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`)
|
||||
- Check the release worked, (e.g. `abra upgrade; abra -v`)
|
||||
|
||||
@ -300,12 +284,12 @@ For developers, while using this `-beta` format, the `y` part is the "major" ver
|
||||
|
||||
### `godotenv`
|
||||
|
||||
We maintain a fork of [godotenv](https://git.coopcloud.tech/coop-cloud/godotenv) because we need inline comment parsing for environment files. You can upgrade the version here by running `go get git.coopcloud.tech/coop-cloud/godotenv@0<COMMID>` where `<commit>` is the latest commit you want to pin to. See [`abra#391`](https://git.coopcloud.tech/coop-cloud/abra/pulls/391) for more.
|
||||
We maintain a fork of [godotenv](https://git.coopcloud.tech/toolshed/godotenv) because we need inline comment parsing for environment files. You can upgrade the version here by running `go get git.coopcloud.tech/toolshed/godotenv@0<COMMID>` where `<commit>` is the latest commit you want to pin to. See [`abra#391`](https://git.coopcloud.tech/toolshed/abra/pulls/391) for more.
|
||||
|
||||
### `docker/client`
|
||||
|
||||
A number of modules in [pkg/upstream](https://git.coopcloud.tech/coop-cloud/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.
|
||||
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.
|
||||
|
||||
### `github.com/schultz-is/passgen`
|
||||
|
||||
Due to [`coop-cloud/organising#358`](https://git.coopcloud.tech/coop-cloud/organising/issues/358).
|
||||
Due to [`toolshed/organising#358`](https://git.coopcloud.tech/toolshed/organising/issues/358).
|
||||
|
@ -4,8 +4,8 @@ title: Abra
|
||||
|
||||
<a href="https://github.com/egonelbre/gophers"><img align="right" width="250" src="https://github.com/egonelbre/gophers/raw/master/.thumb/sketch/adventure/poking-fire.png"/></a>
|
||||
|
||||
[](https://build.coopcloud.tech/coop-cloud/abra)
|
||||
[](https://goreportcard.com/report/git.coopcloud.tech/coop-cloud/abra)
|
||||
[](https://build.coopcloud.tech/toolshed/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:
|
||||
|
@ -4,7 +4,7 @@ title: Install
|
||||
|
||||
## Installer script source
|
||||
|
||||
You can view that [here](https://git.coopcloud.tech/coop-cloud/abra/src/branch/main/scripts/installer/installer).
|
||||
You can view that [here](https://git.coopcloud.tech/toolshed/abra/src/branch/main/scripts/installer/installer).
|
||||
|
||||
## Installer prerequisites
|
||||
|
||||
@ -43,7 +43,7 @@ curl https://install.abra.coopcloud.tech | bash -s -- --rc
|
||||
## Manual verification
|
||||
|
||||
You can download the `abra` binary yourself from the [releases
|
||||
page](https://git.coopcloud.tech/coop-cloud/abra/releases) along with the
|
||||
page](https://git.coopcloud.tech/toolshed/abra/releases) along with the
|
||||
`checksums.txt` file and verify it's integrity with the following command.
|
||||
|
||||
```bash
|
||||
@ -67,7 +67,7 @@ Follow the guide [here](https://docs.coopcloud.tech/abra/hack/)
|
||||
```
|
||||
docker run \
|
||||
-v $HOME/.abra:/.abra \
|
||||
git.coopcloud.tech/coop-cloud/abra app ls
|
||||
git.coopcloud.tech/toolshed/abra app ls
|
||||
```
|
||||
|
||||
!!! note
|
||||
|
@ -2,7 +2,7 @@
|
||||
title: Recipes
|
||||
---
|
||||
|
||||
_Recipes_ are what we call the configuration file used to deploy apps with our `abra` CLI tool. A longer explanation is in the [glossary](/glossary#recipe). Our _Catalogue_ is a web interface for exploring the currently available configurations, therefore which apps can be deployed.
|
||||
_Recipes_ are what we call the configuration file used to deploy apps with our `abra` CLI tool. A longer explanation is in the [glossary](/intro/glossary#recipe). Our _Catalogue_ is a web interface for exploring the currently available configurations, therefore which apps can be deployed.
|
||||
|
||||
### Catalogue
|
||||
|
||||
@ -84,7 +84,7 @@ Currently, recipe maintainers need to update the scores in this section manually
|
||||
## Requesting Recipes
|
||||
|
||||
If you'd like to see a new recipe packaged there are two options for you. First is to contribte one as a _Maintainer_
|
||||
The second option is to make a request on the [`recipes-wishlist`](https://git.coopcloud.tech/coop-cloud/recipes-wishlist) repository issue tracker.
|
||||
The second option is to make a request on the [`recipes-wishlist`](https://git.coopcloud.tech/toolshed/recipes-wishlist) repository issue tracker.
|
||||
|
||||
If no one is around to help, you can always take a run at it yourself, go to the [Maintainers](/maintainers/) section to help you on your way.
|
||||
|
||||
@ -100,7 +100,7 @@ If no one is around to help, you can always take a run at it yourself, go to the
|
||||
|
||||
Don't feel up to the task? Open an issue in the `recipes-wishlist` repository
|
||||
|
||||
[Request Recipe](https://git.coopcloud.tech/coop-cloud/recipes-wishlist){ .md-button .md-button--primary }
|
||||
[Request Recipe](https://git.coopcloud.tech/toolshed/recipes-wishlist){ .md-button .md-button--primary }
|
||||
|
||||
</div>
|
||||
|
||||
|
@ -4,7 +4,7 @@ title: Troubleshoot
|
||||
|
||||
## Where do I report `abra` bugs / feature requests?
|
||||
|
||||
You can use [this issue tracker](https://git.coopcloud.tech/coop-cloud/organising/issues/new/choose).
|
||||
You can use [this issue tracker](https://git.coopcloud.tech/toolshed/organising/issues/new/choose).
|
||||
|
||||
## SSH connection issues?
|
||||
|
||||
@ -63,22 +63,22 @@ We're still waiting for upstream patch which resovles this.
|
||||
|
||||
## Why can't `abra` support multiline in `.env` files?
|
||||
|
||||
We're sorry, it's an issue with an upstream dependency. See [`#291`](https://git.coopcloud.tech/coop-cloud/organising/issues/291) for more.
|
||||
We're sorry, it's an issue with an upstream dependency. See [`#291`](https://git.coopcloud.tech/toolshed/organising/issues/291) for more.
|
||||
|
||||
## I need some feature from the old deprecated bash abra?
|
||||
|
||||
There is an archive of the [old code here](https://git.coopcloud.tech/coop-cloud/abra-bash).
|
||||
There is an archive of the [old code here](https://git.coopcloud.tech/toolshed/abra-bash).
|
||||
|
||||
You can install it alongside the [supported version of Abra](https://git.coopcloud.tech/coop-cloud/abra) by using these commands:
|
||||
You can install it alongside the [supported version of Abra](https://git.coopcloud.tech/toolshed/abra) by using these commands:
|
||||
|
||||
```bash
|
||||
git clone https://git.coopcloud.tech/coop-cloud/abra-bash ~/.abra/bash-src
|
||||
git clone https://git.coopcloud.tech/toolshed/abra-bash ~/.abra/bash-src
|
||||
ln -s ~/.abra/bash-src/abra ~/.local/bin/babra
|
||||
```
|
||||
|
||||
## "Network not found" when deploying?
|
||||
|
||||
This appears to be an upstream issue for which we can't do much in `abra` to solve. See [`coop-cloud/organising#420`](https://git.coopcloud.tech/coop-cloud/organising/issues/420) for more info. The work-around is to leave more time in between undeploy/deploy operations so the runtime can catch up.
|
||||
This appears to be an upstream issue for which we can't do much in `abra` to solve. See [`toolshed/organising#420`](https://git.coopcloud.tech/toolshed/organising/issues/420) for more info. The work-around is to leave more time in between undeploy/deploy operations so the runtime can catch up.
|
||||
|
||||
## Caller path in debug stacktrace doesn't exist
|
||||
|
||||
|
@ -16,9 +16,116 @@ abra upgrade
|
||||
abra upgrade --rc
|
||||
```
|
||||
|
||||
### Manually
|
||||
|
||||
You can also download a release manually. Go to the [releases
|
||||
page](https://git.coopcloud.tech/toolshed/abra/releases), download the release
|
||||
file, confirm the checksum and untar it.
|
||||
|
||||
For example, for release candidate `0.10.0-rc1-beta` and `linux_amd64`.
|
||||
Download the release file.
|
||||
|
||||
```
|
||||
wget https://git.coopcloud.tech/toolshed/abra/releases/download/0.10.0-rc1-beta/abra_0.10.0-rc1-beta_linux_amd64.tar.gz
|
||||
```
|
||||
|
||||
Confirm the checksum.
|
||||
|
||||
```
|
||||
wget https://git.coopcloud.tech/toolshed/abra/releases/download/0.10.0-rc1-beta/checksums.txt
|
||||
cat checksums.txt
|
||||
sha256sum abra_0.10.0-rc1-beta_linux_amd64.tar.gz
|
||||
```
|
||||
|
||||
Untar the release.
|
||||
|
||||
```
|
||||
tar -xvf abra_0.10.0-rc1-beta_linux_amd64.tar.gz
|
||||
```
|
||||
|
||||
And test things work.
|
||||
|
||||
```
|
||||
./abra -v
|
||||
```
|
||||
|
||||
## Migration guides
|
||||
|
||||
> General release notes are [here](https://git.coopcloud.tech/coop-cloud/abra/releases/)
|
||||
> General release notes are [here](https://git.coopcloud.tech/toolshed/abra/releases/)
|
||||
|
||||
### `0.9.x-beta` -> `0.10.x-beta`
|
||||
|
||||
> 🎺🎺🎺 Get the [release candidate](https://git.coopcloud.tech/toolshed/abra/releases/tag/0.10.0-rc1-beta) 🎺🎺🎺
|
||||
|
||||
* `abra` will now write the app deployment version to the app env file
|
||||
(`$ABRA_DIR/servers/<server>/<domain>.env`) against the `TYPE=/RECIPE=` env
|
||||
var. This has a number of implications which are detailed in the [release
|
||||
announcement post](https://coopcloud.tech/blog/new-year-status-update-25/).
|
||||
The current `v0.9.x` series of `abra` will not be able to parse this version.
|
||||
So, if you're testing the release candidate, you might to clean up your
|
||||
`.env` files afterwards.
|
||||
|
||||
* We have finally migrated from [`urfave/cli`](https://github.com/urfave/cli)
|
||||
to [`spf13/cobra`](https://cobra.dev) as our command-line handling library.
|
||||
This means we should (hopefully!) not have to deal with so many command-line
|
||||
breaking changes in the future, e.g. how `--` is handled, how flags/args are
|
||||
parsed and so on. We expect to maintain compatibility across this migration,
|
||||
however you might run into something we didn't expect. Please do let us know.
|
||||
|
||||
* `spf13/cobra` does not support "shorthand" flags with multiple characters.
|
||||
So, the shorthard flags for `--git-name` / `--git-email` on `abra recipe new`
|
||||
are now `-N` / `-e` respectively.
|
||||
|
||||
* Auto-completion for `abra` is handled differently now. See `abra autocomplete
|
||||
--help` for more. The full help output is available for each specific shell,
|
||||
e.g. `abra autocomplete zsh --help`. It is now generated on the fly.
|
||||
|
||||
* Several commands now make use of the `--chaos/-C` commands, such as `abra app
|
||||
ps` and `abra app cp`. See `--help` for more.
|
||||
|
||||
* `+ unstaged changes` is shown as `+U` in the overviews. This change was made
|
||||
to support more compact display layouts. This marker will always be shown in
|
||||
bold (**+U**) as a visual aid.
|
||||
|
||||
* `abra` will no longer attempt to parse your `~/.ssh/config`. This means that
|
||||
whatever you configure in your `~/.ssh/config` is the source of truth and
|
||||
`abra` does not try to guess connection details. `abra` now *only* invokes
|
||||
`/usr/bin/ssh`. This also means that `--problems/-p` goes away on `abra
|
||||
server list`.
|
||||
|
||||
* `abra app backup` / `abra app restore` now officially use
|
||||
[`backup-bot-two`](https://git.coopcloud.tech/coop-cloud/backup-bot-two)! We
|
||||
are still discussing how to handle this transition wrt. the original
|
||||
`backup-bot`. Please see [this
|
||||
ticket](https://git.coopcloud.tech/coop-cloud/backup-bot/issues/5) for more.
|
||||
|
||||
* `--no-domain-checks` has been removed from `abra server add`. See
|
||||
[`#631`](https://git.coopcloud.tech/toolshed/organising/issues/631) for more.
|
||||
|
||||
* The output of `abra app ps` is less redundant in order to 1) reduce how much
|
||||
horizontal width is required to render the table and 2) simplify the amount
|
||||
of information shown. The `-w` option was also retired, you can use the
|
||||
standard `watch` command, e.g. `watch abra app ps ...` to get the same
|
||||
functionality.
|
||||
|
||||
* Several overview screens have changed their layout. E.g. `abra app deploy`
|
||||
now shows more (hopefully!) useful information. These changes have been made
|
||||
to accomodate the work done around operator collaboration and stable
|
||||
versioning.
|
||||
|
||||
* `abra app errors` went away. It never really worked and was retired. You can
|
||||
rely on `abra app logs` for the time being.
|
||||
|
||||
* It's not possible to `--chaos/-C` on `upgrade` / `rollback`. See
|
||||
[`#559`](https://git.coopcloud.tech/toolshed/organising/issues/559) for
|
||||
more.
|
||||
|
||||
* `main` will be chosen for new repositories created by `abra`. `abra` will
|
||||
also attempt to clone the `main` branch first instead of the `master` branch.
|
||||
The `master` branch is tried afterwards. This is mainly due to the fact that
|
||||
the majority of our recipes use the `main` branch.
|
||||
|
||||
* `abra recipe fetch` now accepts an `--all` flag to fetch all repositories.
|
||||
|
||||
### `0.8.x-beta` -> `0.9.x-beta`
|
||||
|
||||
@ -38,7 +145,7 @@ None at this time.
|
||||
|
||||
- Secrets are now only generated by reading the recipe config, not the env
|
||||
vars. This should hopefully not affect you. If you're seeing weird behaviour,
|
||||
please see [`#464`](https://git.coopcloud.tech/coop-cloud/organising/issues/464).
|
||||
please see [`#464`](https://git.coopcloud.tech/toolshed/organising/issues/464).
|
||||
|
||||
- There is a new linting rule for catching invalid tags in recipe versions.
|
||||
This is an seemingly unavoidable issue that requires some maintenance work.
|
||||
@ -72,13 +179,13 @@ None at this time.
|
||||
- Using `{{ .Domain }}` in recipe `.envrc.sample` files went away because it
|
||||
was portable enough. We revert to replacing e.g `gitea.example.com` with the
|
||||
domain. See
|
||||
[`8fad34e`](https://git.coopcloud.tech/coop-cloud/abra/commit/8fad34e) for
|
||||
[`8fad34e`](https://git.coopcloud.tech/toolshed/abra/commit/8fad34e) for
|
||||
more.
|
||||
|
||||
- If your `abra.sh` scripts depend on `/bin/sh` and `/bin/bash` is available in
|
||||
the container then `/bin/bash` will be used from now on. `/bin/sh` is only
|
||||
now used if `/bin/bash` is not available. See
|
||||
[`7f745ff`](https://git.coopcloud.tech/coop-cloud/abra/commit/7f745ff) for
|
||||
[`7f745ff`](https://git.coopcloud.tech/toolshed/abra/commit/7f745ff) for
|
||||
more.
|
||||
|
||||
### `v0.4.x` -> `v0.5.x`
|
||||
|
@ -26,7 +26,7 @@ Abra is a critical infrastructural resource because operators and recipe maintai
|
||||
|
||||
## Link to project repository
|
||||
|
||||
[`git.coopcloud.tech/coop-cloud/abra`](https://git.coopcloud.tech/coop-cloud/abra)
|
||||
[`git.coopcloud.tech/toolshed/abra`](https://git.coopcloud.tech/toolshed/abra)
|
||||
|
||||
## Link to project website
|
||||
|
||||
@ -90,9 +90,9 @@ The second is a new challenge in which we must implement larger scale enhancemen
|
||||
|
||||
We currently categorise these two development trajectories under the following project boards:
|
||||
|
||||
* [Critical fixes (15 tickets at time of writing)](https://git.coopcloud.tech/coop-cloud/organising/projects/24)
|
||||
* [Critical fixes (15 tickets at time of writing)](https://git.coopcloud.tech/toolshed/organising/projects/24)
|
||||
|
||||
* [Medium/large enhancements (15 tickets at time of writing)](https://git.coopcloud.tech/coop-cloud/organising/projects/25)
|
||||
* [Medium/large enhancements (15 tickets at time of writing)](https://git.coopcloud.tech/toolshed/organising/projects/25)
|
||||
|
||||
Abra has proven itself as a resilient toolset over 3 years of development and adoption. However, with the increase in scope of fixes and proposals for large scale changes, is at risk of falling behind and at worst, becoming an obstacle to day-to-day operations as the ecosystem of open source infrastructure management continues to change.
|
||||
|
||||
|
@ -11,14 +11,14 @@ title: 2024-03-29
|
||||
## Agenda
|
||||
|
||||
- checking in
|
||||
- abra release planning https://git.coopcloud.tech/coop-cloud/organising/issues/583
|
||||
- abra release planning https://git.coopcloud.tech/toolshed/organising/issues/583
|
||||
- reforms to fedi process
|
||||
- symptoms
|
||||
- eotl vote delayed weeks
|
||||
- many members not paying dues, no waiver agreed
|
||||
- vera / Flancia left all chats?
|
||||
- proposals
|
||||
- [define fedi member reponsibilities](https://git.coopcloud.tech/coop-cloud/organising/issues/579)
|
||||
- [define fedi member reponsibilities](https://git.coopcloud.tech/toolshed/organising/issues/579)
|
||||
- exit criteria for fedi members
|
||||
- delay x quorom decision making
|
||||
- rolling "credit system" for doing work
|
||||
@ -50,7 +50,7 @@ if i create a new version of a recipe, the catalogue is not even at all. it just
|
||||
precomputing means saving resources later on
|
||||
|
||||
With the operator collaboration topic, it will be possible to specificy an app recipe with a git location, it is then possible to skip the catalogue.
|
||||
https://git.coopcloud.tech/coop-cloud/organising/issues/533#issuecomment-19038
|
||||
https://git.coopcloud.tech/toolshed/organising/issues/533#issuecomment-19038
|
||||
|
||||
recipes.coopcloud.tech (the Elm app) is reading the JSON
|
||||
|
||||
@ -66,7 +66,7 @@ Can also ask Autonomic and/or whoever else feels like they can help.
|
||||
|
||||
#### Cli Argument Handling
|
||||
|
||||
https://git.coopcloud.tech/coop-cloud/organising/issues/581
|
||||
https://git.coopcloud.tech/toolshed/organising/issues/581
|
||||
|
||||
Upgrade to `urfave/cli` version 2 will enforce `abra app command command [command options] <domain> [<service>] <command> [-- <args>]`
|
||||
|
||||
@ -96,7 +96,7 @@ Btw emoji polls are actually broken for some clients 😱
|
||||
|
||||
### Fedi process reforms
|
||||
|
||||
https://git.coopcloud.tech/coop-cloud/organising/issues/579
|
||||
https://git.coopcloud.tech/toolshed/organising/issues/579
|
||||
|
||||
- pay yearly dues or get waiver (don't pay)
|
||||
- actively participate in voting
|
||||
|
@ -20,7 +20,7 @@ title: 2024-04-17
|
||||
|
||||
* Non-Federation tasks specific bounty / funding `@basebuilder`
|
||||
* Website and docs work to better showcase federation - `@kawaiipunk`
|
||||
* https://git.coopcloud.tech/coop-cloud/organising/milestone/43
|
||||
* https://git.coopcloud.tech/toolshed/organising/milestone/43
|
||||
* Recipe maintainence proposal - `@kawaiipunk`
|
||||
* "Hacking velocity = slow & money" (RE: recent fedi orga chat) `@d1`
|
||||
* Continuing budget 001 for meeting attendance, resolution 004 technically only covered 6 months to oct 2023 `@3wc` (but I won't be there)
|
||||
@ -56,8 +56,8 @@ What to look out for:
|
||||
- Redirects (mainly for recipes)
|
||||
- SSH will break though -> could make a migration script for that?
|
||||
|
||||
https://git.coopcloud.tech/coop-cloud/organising/milestone/45
|
||||
https://git.coopcloud.tech/coop-cloud/organising/issues/569
|
||||
https://git.coopcloud.tech/toolshed/organising/milestone/45
|
||||
https://git.coopcloud.tech/toolshed/organising/issues/569
|
||||
|
||||
Maybe "tools" / "projects" not needed, only "recipes" / "other".
|
||||
|
||||
|
@ -4,7 +4,7 @@
|
||||
|
||||
* Federation Stuff / Current state
|
||||
* Funding for Maintenance work
|
||||
* Design Operator Collaboration https://git.coopcloud.tech/coop-cloud/organising/issues/467
|
||||
* Design Operator Collaboration https://git.coopcloud.tech/toolshed/organising/issues/467
|
||||
* HOWTO finish Restore https://git.coopcloud.tech/coop-cloud/backup-bot-two/issues/42
|
||||
|
||||
### Introductions
|
||||
@ -26,7 +26,7 @@ a good idea by d1, would be nice if we can get one or two persons to commit to t
|
||||
|
||||
### Backupbot
|
||||
|
||||
- spec: https://git.coopcloud.tech/coop-cloud/docs.coopcloud.tech/pulls/258
|
||||
- spec: https://git.coopcloud.tech/toolshed/docs.coopcloud.tech/pulls/258
|
||||
|
||||
- what to do if multiple backupbot.backup=false / true
|
||||
- backupbot will ignore false if true was set
|
||||
|
@ -7,7 +7,7 @@
|
||||
|
||||
## Summary
|
||||
|
||||
Create policies on recipe maintainence that meet industry standards, for example the designation of a recipe as stable or not if the recipe meets a certain critera and having named maintainers.
|
||||
Create policies on recipe maintainence that meet industry standards, for example the designation of a recipe as stable or not if the recipe meets certain critera and having named maintainers.
|
||||
|
||||
## Details
|
||||
|
||||
@ -57,9 +57,9 @@ If no one claims active responsibility for a recipe, its git repo will be archiv
|
||||
|
||||
- Docs updates to include explanations
|
||||
- Ongoing coworks to add catergories to all recipes
|
||||
- Package maintenance status will be added to the README's metdata on all recipes. Rname existing "Status" to Features, use Status for this maintenance status.
|
||||
- Package maintenance status will be added to the README metdata on all recipes. Rename existing "Status" to Features, use Status for this maintenance status.
|
||||
- Add maintenance status to be visible on recipes.coopcloud.tech
|
||||
- Every three months we go through the recipes and garden the status is and ping maintainer's etc.
|
||||
- Every three months we go through the recipes and garden the status is and ping maintainers etc.
|
||||
|
||||
# Pre-Propose Feedback from community
|
||||
* ~~Are maintainers community members or fedi members?~~
|
||||
|
28
docs/federation/resolutions/in-progress/026.md
Normal file
28
docs/federation/resolutions/in-progress/026.md
Normal file
@ -0,0 +1,28 @@
|
||||
---
|
||||
title: "Resolution 026"
|
||||
---
|
||||
|
||||
- Topic: Budget 014: Backpay for `v0.10.x` abra release work
|
||||
- Date: 08-01-2025
|
||||
- Deadline: 22-01-2025
|
||||
- Size: Large
|
||||
|
||||
### Summary
|
||||
|
||||
`@decentral1se` had spoons and cycles from roughly December 27th 2024 - January 5th January to make the final push of development work to get the new `abra` release out.
|
||||
|
||||
See the **WIP** [migration docs](https://docs.coopcloud.tech/abra/upgrade/#09x-beta-010x-beta) and [release blogpost](https://pad.local-it.org/G1TOcidEQtyArJU9gI0SDw?both#New-abra-release-candidate) for more information. TLDR; we have a release candidate that you can test today.
|
||||
|
||||
In this resolution, budget is being asked to *retroactively* cover this development work as "backpay".
|
||||
|
||||
### Details (Budget 014)
|
||||
|
||||
An [invoice was submitted already](https://opencollective.com/coop-cloud/expenses/234126) on our Open Collective based on a "fuzzy consensus" within the Co-op Cloud Federation chat. However, on reflection, concerns were raised that it would be better to follow our agreed decision making process and submit a resolution to vote.
|
||||
|
||||
There are 15 hours that are covered by [`R021`](https://docs.coopcloud.tech/federation/resolutions/passed/021/). However, the development of this work ran over by 3 hours. The remaining development work took 32 hours. The details of the specific tickets are on the [Open Collective invoice](https://opencollective.com/coop-cloud/expenses/234126). That brings the total amount of hours to 52.
|
||||
|
||||
#### Budget
|
||||
|
||||
`@decentral1se` has *already* carried out this work.
|
||||
|
||||
Proposed budget of 52 hrs * 20 EUR: 1040 EUR
|
@ -11,9 +11,9 @@ title: "Resolution 010"
|
||||
|
||||
We propose to have a standing budget of 10 hrs / month available for fixes in Abra, Co-op Cloud recipes and other critical tools (e.g. recipes.coopcloud.tech) in the Co-op Cloud ecosystem.
|
||||
|
||||
A fix is deemed critial when it is listed on this coop-cloud/organising board:
|
||||
A fix is deemed critical when it is listed on this toolshed/organising board:
|
||||
|
||||
> https://git.coopcloud.tech/coop-cloud/organising/projects/24
|
||||
> https://git.coopcloud.tech/toolshed/organising/projects/24
|
||||
|
||||
This board is collectively gardened by Co-op Cloud participants (both federation members and not). The process for adding a ticket to the board requires getting confirmation from at least one other member of the federation.
|
||||
|
||||
|
@ -19,7 +19,7 @@ It's time to build a robust Abra integration test suite which can help us stop r
|
||||
|
||||
References so far:
|
||||
- [3wc & myself (d1) have had a planning meeting](https://pad.autonomic.zone/kdLrPXMSSb2TZezCBhdYtw?edit)
|
||||
- [The first PR and proof of concept has landed in Abra](https://git.coopcloud.tech/coop-cloud/abra/pulls/347)
|
||||
- [The first PR and proof of concept has landed in Abra](https://git.coopcloud.tech/toolshed/abra/pulls/347)
|
||||
- [Initial documentation has been written](https://docs.coopcloud.tech/abra/hack/#integration-tests)
|
||||
|
||||
With some further experimentation, I'm relatively confident that this approach will allow us to implement an integration test suite which covers the majority of the Abra functionality. It's *a lot* of work. I'm estimating this to come in at 30 hours of work.
|
||||
|
@ -22,14 +22,14 @@ estimating: small (1-3 hours), medium (3-8 hours), large (8-15 hours) & order is
|
||||
|
||||
| NAME | estimation |
|
||||
| ---- | ----- |
|
||||
| [#535 Comment parsing and modifiers](https://git.coopcloud.tech/coop-cloud/organising/issues/535) | Large |
|
||||
| [#519 abra app new `[<recipe>]` `[<version>]`](https://git.coopcloud.tech/coop-cloud/organising/issues/519) | Medium |
|
||||
| [#518 Abra fails silently if required image doesn't exist](https://git.coopcloud.tech/coop-cloud/organising/issues/518) | Medium |
|
||||
| [#527 abra catalogue generate `<recipe name>` ignores the specified recipe](https://git.coopcloud.tech/coop-cloud/organising/issues/527) | Small |
|
||||
| [#509 abra app remove could wait until volume is not in use](https://git.coopcloud.tech/coop-cloud/organising/issues/509) | Medium |
|
||||
| [#530 abra recipe fetch can only fetch a single recipe](https://git.coopcloud.tech/coop-cloud/organising/issues/530) | Medium |
|
||||
| [#525 prevent abra app cp from applying file permissions.](https://git.coopcloud.tech/coop-cloud/organising/issues/525) | Medium |
|
||||
| [#537 Fix the operators tutorial](https://git.coopcloud.tech/coop-cloud/organising/issues/537) | Medium |
|
||||
| [#535 Comment parsing and modifiers](https://git.coopcloud.tech/toolshed/organising/issues/535) | Large |
|
||||
| [#519 abra app new `[<recipe>]` `[<version>]`](https://git.coopcloud.tech/toolshed/organising/issues/519) | Medium |
|
||||
| [#518 Abra fails silently if required image doesn't exist](https://git.coopcloud.tech/toolshed/organising/issues/518) | Medium |
|
||||
| [#527 abra catalogue generate `<recipe name>` ignores the specified recipe](https://git.coopcloud.tech/toolshed/organising/issues/527) | Small |
|
||||
| [#509 abra app remove could wait until volume is not in use](https://git.coopcloud.tech/toolshed/organising/issues/509) | Medium |
|
||||
| [#530 abra recipe fetch can only fetch a single recipe](https://git.coopcloud.tech/toolshed/organising/issues/530) | Medium |
|
||||
| [#525 prevent abra app cp from applying file permissions.](https://git.coopcloud.tech/toolshed/organising/issues/525) | Medium |
|
||||
| [#537 Fix the operators tutorial](https://git.coopcloud.tech/toolshed/organising/issues/537) | Medium |
|
||||
|
||||
Estimation: best case: (8 * 1) + (3 * 6) + (1 * 1) = 27 hours
|
||||
Estimation: worst case: (15 * 1) + (8 * 6) + (1 * 3) = 73 hours
|
||||
|
@ -10,7 +10,7 @@ title: "Resolution 020"
|
||||
### Summary
|
||||
|
||||
Motivated by the collective release planning:
|
||||
[`#583`](https://git.coopcloud.tech/coop-cloud/organising/issues/583) under
|
||||
[`#583`](https://git.coopcloud.tech/toolshed/organising/issues/583) under
|
||||
"Automate Integration Test Suite".
|
||||
|
||||
The latest `abra` release (`0.9.x`) was heavily delayed due to several issues.
|
||||
|
@ -9,7 +9,7 @@ title: "Resolution 021"
|
||||
|
||||
### Summary
|
||||
|
||||
Migrate away from our current command-line dependency so `abra` usage is more predictable. The goal is to maintain feature parity with no breaking changes. The main advantage that we will get is robust and flexible handling of flags/arguments which don't depend on forcing a specific order (see [`#581`](https://git.coopcloud.tech/coop-cloud/organising/issues/581)). There are other bonuses such as built-in support for auto-completion, better handling of example usage, improved support for global flags (`--debug`) and manpage support.
|
||||
Migrate away from our current command-line dependency so `abra` usage is more predictable. The goal is to maintain feature parity with no breaking changes. The main advantage that we will get is robust and flexible handling of flags/arguments which don't depend on forcing a specific order (see [`#581`](https://git.coopcloud.tech/toolshed/organising/issues/581)). There are other bonuses such as built-in support for auto-completion, better handling of example usage, improved support for global flags (`--debug`) and manpage support.
|
||||
|
||||
### Details (Budget 011)
|
||||
|
||||
@ -44,7 +44,7 @@ This means that some commands allow both "after" and "before" style and some onl
|
||||
|
||||
#### The solution
|
||||
|
||||
[Several](https://git.coopcloud.tech/coop-cloud/abra/pulls/404) [attempts](https://git.coopcloud.tech/coop-cloud/abra/pulls/435) have been made to upgrade `urfave/cli` to fix this behaviour. However, as it turns out, it is **highly unlikely** that they will fix this upstream: [`urfave/cli#1950`](https://github.com/urfave/cli/issues/1950) [`urfave/cli#1928`](https://github.com/urfave/cli/pull/1928) (and even this proposal does not really include the desired robust flexible handling we need).
|
||||
[Several](https://git.coopcloud.tech/toolshed/abra/pulls/404) [attempts](https://git.coopcloud.tech/toolshed/abra/pulls/435) have been made to upgrade `urfave/cli` to fix this behaviour. However, as it turns out, it is **highly unlikely** that they will fix this upstream: [`urfave/cli#1950`](https://github.com/urfave/cli/issues/1950) [`urfave/cli#1928`](https://github.com/urfave/cli/pull/1928) (and even this proposal does not really include the desired robust flexible handling we need).
|
||||
|
||||
`@decentral1se` has done a spike to confirm that [`cobra`](https://cobra.dev) handles flexible handling of arguments/flags. Those reading this proposal and wishing to try it out for themselves can take [Hugo](https://gohugo.io/) for a spin (it uses `cobra` as the underlying command-line library).
|
||||
|
||||
|
@ -6,7 +6,7 @@ title: "Resolution 013"
|
||||
|
||||
This resolution has been amended! The main change was to remove automatic
|
||||
git synchronisation; please see [the file
|
||||
history](https://git.coopcloud.tech/coop-cloud/docs.coopcloud.tech/commits/branch/main/docs/federation/resolutions/in-progress/013.md) for a full run-down.
|
||||
history](https://git.coopcloud.tech/toolshed/docs.coopcloud.tech/commits/branch/main/docs/federation/resolutions/in-progress/013.md) for a full run-down.
|
||||
|
||||
- Budget 007: Operator sync
|
||||
- Date: 2024-01-??
|
||||
@ -15,7 +15,7 @@ title: "Resolution 013"
|
||||
|
||||
### Summary
|
||||
|
||||
As highlighted in several tickets (e.g. [`#434`](https://git.coopcloud.tech/coop-cloud/organising/issues/434), [`#467`](https://git.coopcloud.tech/coop-cloud/organising/issues/467)), several operators working together on the same server routinely run into deployment instability. This is due to the fact that we do not store the deployment version of the apps.
|
||||
As highlighted in several tickets (e.g. [`#434`](https://git.coopcloud.tech/toolshed/organising/issues/434), [`#467`](https://git.coopcloud.tech/toolshed/organising/issues/467)), several operators working together on the same server routinely run into deployment instability. This is due to the fact that we do not store the deployment version of the apps.
|
||||
|
||||
With this proposal, we would like to address the synchronisation of app deployment versions. This is being called "Operator sync". What follows is the design proposal which has already received feedback from operators on [this pad](https://pad.riseup.net/p/IebZQkpe3OOpYyVT8f1j-keep).
|
||||
|
||||
|
@ -4,9 +4,11 @@ title: Introduction
|
||||
|
||||
## Who is this for?
|
||||
|
||||
Welcome to the Co-op Cloud documentation 🥳
|
||||
Welcome to the Co-op Cloud documentation 👋
|
||||
|
||||
The documentation is aimed at a technical audience: tech co-ops, collectives and individuals who are curious about Co-op Cloud or are already running and managing Co-op Cloud deployments.
|
||||
In the spirit of transparency and to avoid confusion, we would like to begin with the explanation that this documentation is aimed at a **technical audience**.
|
||||
|
||||
We have written this with the following groups in mind: tech co-ops, collectives and individuals who have familiarity with system administration and libre software communities and are curious about Co-op Cloud or are already running and managing Co-op Cloud deployments.
|
||||
|
||||
A more general public may still find these pages useful but if you're just looking for a quick overview of the project from a less technical perspective, you can take a look at [coopcloud.tech](https://coopcloud.tech).
|
||||
|
||||
@ -16,18 +18,18 @@ We'd be happy to hear feedback about our documentation, if it was helpful, what
|
||||
|
||||
!!! danger "Here be dragons"
|
||||
|
||||
This project is still [beta quality software](https://en.wikipedia.org/wiki/Software_release_life_cycle#Beta) :bomb: Please take that into consideration if you are thinking about using this system in production. We're working hard to make Co-op Cloud stable. In the meantime, this is a good time to help us out with initial testing, feedback, ideas or [join in with development](/get-involved/).
|
||||
This project is still [beta quality software](https://en.wikipedia.org/wiki/Software_release_life_cycle#Beta) :bomb: Please take that into consideration if you are thinking about using this system in production. We're working hard to make Co-op Cloud stable. In the meantime, this is a good time to help us out with initial testing, feedback, ideas or [join in with development](/intro/get-involved/).
|
||||
|
||||
- [Operators guide](/operators/): You run a Co-op Cloud based deployment or want to do so :computer:
|
||||
|
||||
- [Maintainers guide](/maintainers/): You maintain recipes and ensure things run smoothly for operators :tools:
|
||||
|
||||
- [Organisers guide](/organisers): You run meetings, write guidelines & shape our democratic process :fist:
|
||||
- [Organisers guide](/federation/organisers): You run meetings, write guidelines & shape our democratic process :fist:
|
||||
|
||||
- [Recipes](/abra/recipes/): You want to know what recipes are packaged so you can deploy them as apps :nerd:
|
||||
|
||||
- [Abra](/abra): You want to install the command-line client and hack the planet :unicorn:
|
||||
|
||||
- [Get involved](/get-involved): You'd like to help out with the project, we've love to see you stick around :heart:
|
||||
- [Get involved](/intro/get-involved): You'd like to help out with the project, we've love to see you stick around :heart:
|
||||
|
||||
- [Glossary](/glossary/): You'd like clarification about project terminology :book:
|
||||
- [Glossary](/intro/glossary/): You'd like clarification about project terminology :book:
|
||||
|
@ -53,7 +53,7 @@ The core technologies of Co-op Cloud are libre software and enjoy wide adoption
|
||||
- [Containers](#why-containers)
|
||||
- [Compose specification](#why-docker-compose)
|
||||
- [Docker swarm](#why-docker-swarm)
|
||||
- [Abra command-line tool](https://git.autonomic.zone/coop-cloud/abra)
|
||||
- [Abra command-line tool](https://git.autonomic.zone/toolshed/abra)
|
||||
|
||||
## Why containers?
|
||||
|
||||
@ -160,7 +160,7 @@ Yes! Horizontal scaling is one of the ways Co-op Cloud can really shine. `abra`
|
||||
|
||||
## Why only x86 support?
|
||||
|
||||
We would love to do ARM support and hope to get there! We've been testing this and [ran into some issues](https://git.coopcloud.tech/coop-cloud/organising/issues/25). The TLDR; is that a lot of upstream libre app developer communities are not publishing container builds that support ARM. If they are, there are typically subtle differences in the conventions used to build the image as they are mostly done by community members and not directly taken on by the upstream project themselves. Since one of the core goals is to coordinate and reuse upstream packaging work, we see that ARM support requires a lot of organising and community engagement. Perhaps projects themselves will not want to take on this burden? It is not the role of the Co-op Cloud to set up an entire ARM publishing work flow at this moment in time. We see the benefits of supporting ARM and if you've got ideas / thoughts / approaches for how to make progress here, [please get in touch](/intro/contact/).
|
||||
We would love to do ARM support and hope to get there! We've been testing this and [ran into some issues](https://git.coopcloud.tech/toolshed/organising/issues/25). The TLDR; is that a lot of upstream libre app developer communities are not publishing container builds that support ARM. If they are, there are typically subtle differences in the conventions used to build the image as they are mostly done by community members and not directly taken on by the upstream project themselves. Since one of the core goals is to coordinate and reuse upstream packaging work, we see that ARM support requires a lot of organising and community engagement. Perhaps projects themselves will not want to take on this burden? It is not the role of the Co-op Cloud to set up an entire ARM publishing work flow at this moment in time. We see the benefits of supporting ARM and if you've got ideas / thoughts / approaches for how to make progress here, [please get in touch](/intro/contact/).
|
||||
|
||||
Update: [Can I run Co-op Cloud on ARM?](/operators/handbook/#can-i-run-co-op-cloud-on-arm)
|
||||
|
||||
|
@ -4,19 +4,19 @@ title: Get Involved
|
||||
|
||||
## Overview
|
||||
|
||||
> :trumpet: **You don't have to be a programmer to contribute to this project!** :trumpet:
|
||||
> 📢 **You don't have to be a programmer to contribute to this project** 📢
|
||||
|
||||
Firstly, come say hello in our [chat room](/intro/contact/) if you'd like to help out or are interested to learn how :wave:
|
||||
Firstly, come say hello in our [chat room](/intro/contact/) if you'd like to help out or are interested to learn how 👋
|
||||
|
||||
We are happy to have designers, critical thinkers, artists, hackers, documenters, etc. involved in this project! There is a lot of work to do, if you find this project interesting, we want to have you working with us.
|
||||
|
||||
There are a number of "roles" such as "operator", "maintainer", "organiser" which we've tried to come up with to make it more clear how you can relate to the project and how you can find ways to be involved which suit your interests. If you don't fit one of these roles, that is fine.
|
||||
|
||||
We have [an irregular online check-in](/organisers/handbook/#kite-flying-hours) for contributors of this project to let each other know what we're working on, how much time we've spent on it and how to coordinate further work.
|
||||
We have [an irregular online check-in](/federation/organisers/#kite-flying-hours) for contributors of this project to let each other know what we're working on, how much time we've spent on it and how to coordinate further work.
|
||||
|
||||
We have a [status page](/intro/bikemap) showing what we are aiming to achieve in the near future. That gives a good overview of where we're going together.
|
||||
|
||||
We use [issue trackers](https://git.coopcloud.tech/coop-cloud/organising/issues) and [project boards](https://git.coopcloud.tech/coop-cloud/organising/projects) to keep track of what we're working on right now. We collectively review these, to keep track of our time spent vs. budget available.
|
||||
We use [issue trackers](https://git.coopcloud.tech/coop-cloud/organising/issues) and [project boards](https://git.coopcloud.tech/toolshed/projects) to keep track of what we're working on right now. We collectively review these, to keep track of our time spent vs. budget available.
|
||||
|
||||
## Compensation
|
||||
|
@ -4,7 +4,7 @@ title: Glossary
|
||||
|
||||
## Abra
|
||||
|
||||
A command-line tool that has been developed specifically in the context of the Co-op Cloud project for the purpose of making day-to-day operations for [operators](/operators/) and [maintainers](/maintainers/) as convenient as possible. It is libre software, written in [Go](https://go.dev/) and maintained and extended by the community. You can find the source [here](https://git.coopcloud.tech/coop-cloud/abra).
|
||||
A command-line tool that has been developed specifically in the context of the Co-op Cloud project for the purpose of making day-to-day operations for [operators](/operators/) and [maintainers](/maintainers/) as convenient as possible. It is libre software, written in [Go](https://go.dev/) and maintained and extended by the community. You can find the source [here](https://git.coopcloud.tech/toolshed/abra).
|
||||
|
||||
## App
|
||||
|
||||
|
@ -9,5 +9,6 @@ title: Managed hosting
|
||||
The Co-op Cloud is still [beta quality software](https://en.wikipedia.org/wiki/Software_release_life_cycle#Beta) :bomb: but you can still work with a tech co-op or collective to host some part or all of your online digital services with it. Organisations who want to support the project can get in touch with Co-op Cloud service providers via the following list for a quote on what they're looking for and how much it will cost. Service providers can then factor in some percentage of the cost to co-fund the development of this project.
|
||||
|
||||
- [Autonomic Co-op](https://autonomic.zone) (contact: [`helo@autonomic.zone`](mailto:boop@autonomic.zone))
|
||||
- [Local-IT](https://local-it.org/) (contact [`info@local-it.org`](mailto:info@local-it.org))
|
||||
- [makeITsocial](https://makeitsocial.net) (managed hosting, see [price calculator](https://makeitsocial.net/kolli-cloud/))
|
||||
- [Local-IT](https://local-it.org/) ([selfhosting](https://wiki.local-it.org/s/kollicloud-wiki/doc/selfhosting-guide-1xZJt8UIha) & cooperative hosting, contact: [`info@local-it.org`](mailto:info@local-it.org))
|
||||
- [Solisoft](https://solisoft.top) (contact [`contact@solisoft.top`](mailto:contact@solisoft.top))
|
||||
|
@ -6,17 +6,25 @@ From our experiences working and organising as Autonomic, the tech co-op who [in
|
||||
|
||||
## Technological Saviors?
|
||||
|
||||
The urgency for providing an alternative comes out of the understanding that the concentration of our digital lives within the private sphere of corporate providers (e.g. [GAFAM](https://degooglisons-internet.org/en/)) represents a loss of freedom due to the threat to our privacy and self-determination through surveillance and monopolisation.
|
||||
The urgency to build an alternative is based on an analysis of our current reality.
|
||||
|
||||
As a movement, we cannot compete with corporate providers in terms of cost and scale. Their network effects and available capital means that no one project, product or organisation can create the required shift to a more widespread public interest technology.
|
||||
The monopolisation of our digital lives, the stranglehold of corporate control (aka [GAFAM](https://degooglisons-internet.org/en/)), represents a grave threat to our collective freedom, our societies and our hopes for a good life on planet earth.
|
||||
|
||||
> Technology alone will not save us
|
||||
We begin with an acknowledgment of their vast accumulation of network effects and resources. We also acknowledge that no single project, product or organisation can create the required shift to a more widespread public interest technology.
|
||||
|
||||
> Technology alone will not save us.
|
||||
>
|
||||
> Simply deploying libre software is not enough.
|
||||
|
||||
Our strategy is to mutualise our resources to facilitate this shift. _Co-op Cloud_ is an attempt to create a new shared resource - an open and democratically managed, open standards based, copyleft licensed, libre software infrastructure project.
|
||||
Our strategy is to mutualise our resources to facilitate this shift.
|
||||
|
||||
From this base, we can focus on the urgent and necessary social organising work that goes beyond the technical question.
|
||||
We can say that _Co-op Cloud_ is a libre software infrastructure project. It is based on open standards, is copyleft licensed and is open and democratically managed.
|
||||
|
||||
We can also say that _Co-op Cloud_ is a social movement of hosters, hackers, technologists and their allies who defend a vision of collective self-management.
|
||||
|
||||
We are committed to an organisational form which allows us to accumulate knowledge, solidarity, experience and resources. We claim a rich history of grassroots social resistance, direct action and collective liberation.
|
||||
|
||||
We propose to go beyond a reductive technological vision of social change.
|
||||
|
||||
## The Moving Parts
|
||||
|
||||
@ -24,9 +32,9 @@ _Co-op Cloud_ is made up of a few simple, composable pieces. The system does not
|
||||
|
||||
``` mermaid
|
||||
graph LR
|
||||
A[Libre Software\n Apps] --> B{Recipe Packaging};
|
||||
B --> C[CLI Tool];
|
||||
C --> D[Container\n Orchestrator];
|
||||
A[Libre software apps] --> B{Recipe packaging};
|
||||
B --> C[Command-line tool];
|
||||
C --> D[Container orchestrator];
|
||||
```
|
||||
|
||||
Once you [grok](https://en.wikipedia.org/wiki/Grok) this, you grok the moving parts of the entire project. You can then move on to [deploying your first app](/operators/tutorial/#deploy-your-first-app).
|
||||
|
@ -313,7 +313,7 @@ index 1618ef5..6cd754d 100644
|
||||
|
||||
!!! warning "Here be versioning dragons"
|
||||
|
||||
`abra` doesn't understand all image tags unfortunately. There are limitations which we're still running into. You can pass `-a` to have `abra` list all available image tags from the upstream repository and then make a choice manually. See [`tagcmp`](https://git.coopcloud.tech/coop-cloud/tagcmp) for more info on how we implement image parsing.
|
||||
`abra` doesn't understand all image tags unfortunately. There are limitations which we're still running into. You can pass `-a` to have `abra` list all available image tags from the upstream repository and then make a choice manually. See [`tagcmp`](https://git.coopcloud.tech/toolshed/tagcmp) for more info on how we implement image parsing.
|
||||
|
||||
Next, we need to update the label in the recipe, we can do that with `abra recipe sync wordpress`. You'll be prompted by a question asking what kind of upgrade this is. Take a moment to read the output and if it still doesn't make sense, read [this](/maintainers/handbook/#how-are-recipes-are-versioned). Since we're upgrading from `5.8.3` -> `5.9.0`, it is a minor release, so we choose `minor`:
|
||||
|
||||
@ -555,7 +555,7 @@ visibility for other co-op hosters & end-users.
|
||||
|
||||
For now, it is best to [get in touch](https://docs.coopcloud.tech/intro/contact/) if you want to add your recipe to the catalogue.
|
||||
|
||||
In the future, we'd like to support [multiple catalogues](https://git.coopcloud.tech/coop-cloud/organising/issues/139).
|
||||
In the future, we'd like to support [multiple catalogues](https://git.coopcloud.tech/toolshed/organising/issues/139).
|
||||
|
||||
## How do I configure backup/restore?
|
||||
|
||||
@ -567,7 +567,7 @@ backup/restore logic.
|
||||
|
||||
Two of the current "blessed" options are
|
||||
[`backup-bot-two`](https://git.coopcloud.tech/coop-cloud/backup-bot-two) &
|
||||
[`abra`](https://git.coopcloud.tech/coop-cloud/abra).
|
||||
[`abra`](https://git.coopcloud.tech/toolshed/abra).
|
||||
|
||||
#### `backup-bot-two`
|
||||
|
||||
@ -706,7 +706,7 @@ end up with something like `example_org_foo_pass_v1` being used for the secret
|
||||
name.
|
||||
|
||||
Based on a discussion in
|
||||
[`#463`](https://git.coopcloud.tech/coop-cloud/organising/issues/463) and
|
||||
[`#463`](https://git.coopcloud.tech/toolshed/organising/issues/463) and
|
||||
looking on what is implemented currently in existing recipes, we came up with a
|
||||
general rule of thumb that secret names in recipe configurations should be < 12
|
||||
characters long to avoid errors on deployment.
|
@ -10,7 +10,7 @@ Packaging a recipe is basically knowing a bag of about 20 tricks. Once you learn
|
||||
|
||||
The nice thing about packaging is that only one person has to do it and then we all benefit. We've seen that over time, the core of the configuration doesn't really change. New options and versions might come but the config remains quite stable. This is good since it means that your packaging work stays relevant and useful for other maintainers & operators as time goes on.
|
||||
|
||||
Depending on your familiarity with recipes, it might be worth reading [how a recipe is structured](/maintainers/handbook/#how-is-a-recipe-structured) and making clear you understand [what a recipe is](/glossary/#recipe) before continuing.
|
||||
Depending on your familiarity with recipes, it might be worth reading [how a recipe is structured](/maintainers/handbook/#how-is-a-recipe-structured) and making clear you understand [what a recipe is](/intro/glossary/#recipe) before continuing.
|
||||
|
||||
### Making a plan
|
||||
|
@ -311,11 +311,11 @@ If you need to run a command on a container that won't start (eg. the container
|
||||
> ... there was really nothing to it, apart from making sure to use multiarch
|
||||
> or arm images
|
||||
|
||||
See [`#312`](https://git.coopcloud.tech/coop-cloud/organising/issues/312) for more.
|
||||
See [`#312`](https://git.coopcloud.tech/toolshed/organising/issues/312) for more.
|
||||
|
||||
## How do I backup/restore my app?
|
||||
|
||||
If you're app [supports backup/restore](/maintainers/handbook/#how-do-i-configure-backuprestore) then you have two options: [`backup-bot-two`](https://git.coopcloud.tech/coop-cloud/backup-bot-two) & [`abra`](https://git.coopcloud.tech/coop-cloud/abra).
|
||||
If you're app [supports backup/restore](/maintainers/handbook/#how-do-i-configure-backuprestore) then you have two options: [`backup-bot-two`](https://git.coopcloud.tech/coop-cloud/backup-bot-two) & [`abra`](https://git.coopcloud.tech/toolshed/abra).
|
||||
|
||||
With `abra`, you can simply run the commands:
|
||||
|
||||
@ -336,13 +336,15 @@ cheetsheet](/abra/cheat-sheet/#manually-restoring-app-data).
|
||||
MySQL / MariaDB:
|
||||
|
||||
```
|
||||
abra app run foo.bar.com db mysqldump -u root <database> | gzip > ~/.abra/backups/foo.bar.com_db_`date +%F`.sql.gz
|
||||
abra app run foo.bar.com db mysqldump -u root <database> \
|
||||
| gzip > ~/.abra/backups/foo.bar.com_db_`date +%F`.sql.gz
|
||||
```
|
||||
|
||||
Postgres:
|
||||
|
||||
```
|
||||
abra app run foo.bar.com db pg_dump -u root <database> | gzip > ~/.abra/backups/foo.bar.com_db_`date +%F`.sql.gz
|
||||
abra app run foo.bar.com db pg_dump -u root <database> | \
|
||||
gzip > ~/.abra/backups/foo.bar.com_db_`date +%F`.sql.gz
|
||||
```
|
||||
|
||||
If you get errors about database access:
|
||||
@ -351,7 +353,8 @@ If you get errors about database access:
|
||||
something like this:
|
||||
|
||||
```
|
||||
abra app run foo.bar.com db bash -c 'mysqldump -u root -p"$(cat /run/secrets/db_oot_password)" <database>' | gzip > ~/.abra/backups/foo.bar.com_db_`date +%F`.sql.gz
|
||||
abra app run foo.bar.com db \
|
||||
bash -c 'mysqldump -u root -p"$(cat /run/secrets/db_oot_password)" <database>' | gzip > ~/.abra/backups/foo.bar.com_db_`date +%F`.sql.gz
|
||||
```
|
||||
|
||||
## Can I deploy a recipe without `abra`?
|
||||
@ -459,7 +462,7 @@ route requests after. You're free to make as many `$whatever.yml` files in your
|
||||
## Can I use Caddy instead of Traefik?
|
||||
|
||||
Yes, it's possible although currently Quite Experimental! See
|
||||
[`#388`](https://git.coopcloud.tech/coop-cloud/organising/issues/388) for more.
|
||||
[`#388`](https://git.coopcloud.tech/toolshed/organising/issues/388) for more.
|
||||
|
||||
## Running an offline coop-cloud server
|
||||
|
||||
@ -485,7 +488,7 @@ abra app secret insert localhost ssl_key v1 "$(cat localhost.key)"
|
||||
|
||||
!!! warning "This is only available in the currently unreleased version of `abra`"
|
||||
|
||||
Please see [this issue](https://git.coopcloud.tech/coop-cloud/organising/issues/583) to track current progress towards a release. All feedback and testing are welcome on this new feature. The design is not finalised yet.
|
||||
Please see [this issue](https://git.coopcloud.tech/toolshed/organising/issues/583) to track current progress towards a release. All feedback and testing are welcome on this new feature. The design is not finalised yet.
|
||||
|
||||
It is possible to specify a remote recipe in your `.env` file:
|
||||
|
||||
@ -500,3 +503,92 @@ will fetch the remote recipe and create a directory for it under `$ABRA_DIR`
|
||||
```
|
||||
$ABRA_DIR/recipes/mygit_org_myorg_cool-recipe
|
||||
```
|
||||
|
||||
## Saving the version to the app `.env` file
|
||||
|
||||
!!! warning "This is only available in the currently unreleased version of `abra`"
|
||||
|
||||
If you `abra app new`/`abra app deploy`/`abra app upgrade`/`abra app rollback`,
|
||||
the version that is deployed will be written to your app `.env` file. You can
|
||||
see this in the `TYPE=/RECIPE=` line of the `.env` where the recipe name is
|
||||
shown.
|
||||
|
||||
For example, before a deployment of the `custom-html` recipe:
|
||||
|
||||
```
|
||||
TYPE=custom-html
|
||||
```
|
||||
|
||||
And after a deployment of version `1.7.1+1.27.2` of the `custom-html` recipe.
|
||||
|
||||
```
|
||||
TYPE=custom-html:1.7.1+1.27.2
|
||||
```
|
||||
|
||||
This `.env` version is then used as the recipe checkout version for **all**
|
||||
`abra` operations afterwards unless you specify otherwise on the command-line
|
||||
with `[version]` `--chaos/-C` or `--ignore-env-version/-i`.
|
||||
|
||||
## How is the new deployment version determined?
|
||||
|
||||
!!! warning "This is only available in the currently unreleased version of `abra`"
|
||||
|
||||
### `.env` version
|
||||
|
||||
If you `abra app deploy`/`abra app upgrade`/`abra app rollback`, the version
|
||||
that is deployed will be written to your app `.env` file. This is shown in the
|
||||
deployment overview.
|
||||
|
||||
This `.env` version is then used as the recipe checkout version for **all**
|
||||
`abra` operations afterwards unless you specify otherwise on the command-line
|
||||
with `[version]` `--chaos/-C` or `--ignore-env-version/-i`.
|
||||
|
||||
### `abra app deploy`
|
||||
|
||||
This is the most flexible command so it can be hard to follow. It is possible
|
||||
to deploy the following kinds of versions with `abra app deploy`:
|
||||
|
||||
1. latest recipe version (standard `abra app deploy`)
|
||||
2. version retrieved from the app `.env` (`abra app deploy` + `TYPE=custom-html:1.7.1+1.27.2`)
|
||||
3. latest commit (`--chaos/-C` / `abra app deploy` + no released recipe versions)
|
||||
4. latest commit with unstaged changes (`abra app deploy --chaos/-C`)
|
||||
5. recipe version or Git hash (`abra app deploy 1.7.1+1.27.2`)
|
||||
|
||||
The app `.env` version is always used as the recipe checkout version if
|
||||
present.
|
||||
|
||||
For 2), if the app **is undeployed** and there is an app `.env` version
|
||||
present, then it will be used. This is the *only time* the app `.env` version
|
||||
is used using `abra app deploy`. This is done to reduce unwanted upgrades (we
|
||||
do not automatically choose the latest release).
|
||||
|
||||
Use `--ignore-env-version/-i` to deploy the latest release version or commit.
|
||||
In all cases 3-5, the app `.env` version is **ignored** as a version candidate.
|
||||
|
||||
### `abra app upgrade`
|
||||
|
||||
The app must be deployed already to proceed.
|
||||
|
||||
* a new upgrade (standard `abra app upgrade`)
|
||||
* a specific upgrade (`abra app upgrade 1.7.1+1.27.2`)
|
||||
* force re-upgrade (same version, `abra app upgrade --force`)
|
||||
|
||||
The app `.env` version is always used as the recipe checkout version if
|
||||
present.
|
||||
|
||||
However, it is otherwise **ignored** for the version candidate. The "source of
|
||||
truth" for the version candidate is the live deployment of the app.
|
||||
|
||||
### `abra app rollback`
|
||||
|
||||
The app must be deployed already to proceed.
|
||||
|
||||
* a new downgrade (standard `abra app rollback`)
|
||||
* a specific downgrade (`abra app rollback 1.7.1+1.27.2`)
|
||||
* force re-downgrade (same version, `abra app rollback --force`)
|
||||
|
||||
The app `.env` version is always used as the recipe checkout version if
|
||||
present.
|
||||
|
||||
However, it is otherwise **ignored** for the version candidate. The "source of
|
||||
truth" for the version candidate is the live deployment of the app.
|
||||
|
@ -75,7 +75,7 @@ Where `116.203.211.204` can be replaced with the IP address of your server.
|
||||
### Install `abra`
|
||||
|
||||
Now we can install [`abra`](/abra) locally on your machine and hook it up to
|
||||
your server. We support a script-based installation method ([script source](https://git.coopcloud.tech/coop-cloud/abra/src/branch/main/scripts/installer/installer)):
|
||||
your server. We support a script-based installation method ([script source](https://git.coopcloud.tech/toolshed/abra/src/branch/main/scripts/installer/installer)):
|
||||
|
||||
```bash
|
||||
curl https://install.abra.coopcloud.tech | bash
|
||||
@ -99,7 +99,7 @@ you have immediate access to `abra` on the current terminal.
|
||||
export PATH=$PATH:$HOME/.local/bin
|
||||
```
|
||||
|
||||
If you run into issues during installation, [please report a ticket](https://git.coopcloud.tech/coop-cloud/organising/issues/new) :pray: Once you're all set up, we **highly** recommend configuring command-line auto-completion for `abra`. See `abra autocomplete -h` for more on how to do this.
|
||||
If you run into issues during installation, [please report a ticket](https://git.coopcloud.tech/toolshed/organising/issues/new) :pray: Once you're all set up, we **highly** recommend configuring command-line auto-completion for `abra`. See `abra autocomplete -h` for more on how to do this.
|
||||
|
||||
??? question "Can I install `abra` on my server?"
|
||||
|
||||
@ -276,4 +276,4 @@ Add `ENABLE_AUTO_UPDATE=true` to the env config (`abra app config <app name>`) t
|
||||
|
||||
Hopefully you got something running! Well done! The [operators handbook](/operators/handbook) would probably be the next place to go check out if you're looking for more help. Especially on topics of ongoing maintenance.
|
||||
|
||||
If not, please [get in touch](/intro/contact) or [raise a ticket](https://git.coopcloud.tech/coop-cloud/organising/issues/new/choose) and we'll try to help out. We want our operator onboarding to be as smooth as possible, so we do appreciate any feedback we receive.
|
||||
If not, please [get in touch](/intro/contact) or [raise a ticket](https://git.coopcloud.tech/toolshed/organising/issues/new/choose) and we'll try to help out. We want our operator onboarding to be as smooth as possible, so we do appreciate any feedback we receive.
|
||||
|
@ -9,7 +9,7 @@ backup/restore logic.
|
||||
Two of the current "blessed" options are, which both implement the [backupbot specification](link to spec)
|
||||
|
||||
- [`backup-bot-two`](https://git.coopcloud.tech/coop-cloud/backup-bot-two)
|
||||
- [`abra`](https://git.coopcloud.tech/coop-cloud/abra)
|
||||
- [`abra`](https://git.coopcloud.tech/toolshed/abra)
|
||||
|
||||
### `backup-bot-two`
|
||||
|
||||
|
78
mkdocs.yml
78
mkdocs.yml
@ -7,6 +7,7 @@ use_directory_urls: true
|
||||
theme:
|
||||
name: material
|
||||
features:
|
||||
navigation.instant.progress
|
||||
- content.action.edit
|
||||
- navigation.expand
|
||||
- navigation.indexes
|
||||
@ -15,6 +16,7 @@ theme:
|
||||
- navigation.sections
|
||||
- navigation.tabs
|
||||
- navigation.tabs.sticky
|
||||
- navigation.top
|
||||
- navigation.tracking
|
||||
palette:
|
||||
primary: light pink
|
||||
@ -23,7 +25,7 @@ theme:
|
||||
favicon: img/favicon.ico
|
||||
custom_dir: custom_theme/
|
||||
|
||||
copyright: Copyleft 2023 Co-op Cloud
|
||||
copyright: Copyleft 2020-2025 Co-op Cloud
|
||||
|
||||
markdown_extensions:
|
||||
- admonition
|
||||
@ -66,46 +68,28 @@ nav:
|
||||
- "Managed Hosting": intro/managed.md
|
||||
- "Get In Touch": intro/contact.md
|
||||
- "Credits": intro/credits.md
|
||||
- "Operators":
|
||||
- operators/index.md
|
||||
- "New Operators Tutorial": operators/tutorial.md
|
||||
- "Operations Handbook": operators/handbook.md
|
||||
- intro/get-involved.md
|
||||
- intro/glossary.md
|
||||
- "Support Us": intro/support.md
|
||||
- "Maintainers":
|
||||
- maintainers/index.md
|
||||
- "New Maintainers Tutorial": maintainers/tutorial.md
|
||||
- "Packaging Handbook": maintainers/handbook.md
|
||||
- "Organisers":
|
||||
- organisers/index.md
|
||||
- "Organisers Handbook": organisers/handbook.md
|
||||
- "Funding applications":
|
||||
- organisers/funding-applications/index.md
|
||||
- organisers/funding-applications/culture-of-solidarity.md
|
||||
- organisers/funding-applications/ford-foundation.md
|
||||
- organisers/funding-applications/private-funder.md
|
||||
- organisers/funding-applications/sovereign-tech-fund.md
|
||||
- organisers/funding-applications/user-operated-internet.md
|
||||
- "Proposals":
|
||||
- organisers/proposals/index.md
|
||||
- organisers/proposals/federation.md
|
||||
- "Abra":
|
||||
- abra/index.md
|
||||
- "Install": abra/install.md
|
||||
- "Quick Start": abra/quickstart.md
|
||||
- "Upgrade": abra/upgrade.md
|
||||
- "Design": abra/design.md
|
||||
- "Recipes": abra/recipes.md
|
||||
- "Hack": abra/hack.md
|
||||
- "Troubleshoot": abra/trouble.md
|
||||
- "Cheat Sheet": abra/cheat-sheet.md
|
||||
- "Get Involved":
|
||||
- get-involved/index.md
|
||||
- "Support Us": get-involved/support.md
|
||||
- "Operators":
|
||||
- operators/index.md
|
||||
- "New operators Tutorial": operators/tutorial.md
|
||||
- "Operators Handbook": operators/handbook.md
|
||||
- "Federation":
|
||||
- federation/index.md
|
||||
- federation/handbook.md
|
||||
- federation/organisers.md
|
||||
- "Bylaws": federation/bylaws.md
|
||||
- "Finance": federation/finance.md
|
||||
- "Membership": federation/membership.md
|
||||
- "Code of Co-operation": federation/code-of-coop.md
|
||||
- "Proposals":
|
||||
- federation/proposals/index.md
|
||||
- federation/proposals/federation.md
|
||||
- "Resolutions":
|
||||
- federation/resolutions/index.md
|
||||
- "Passed":
|
||||
@ -132,11 +116,15 @@ nav:
|
||||
- federation/resolutions/passed/022.md
|
||||
- federation/resolutions/passed/023.md
|
||||
- federation/resolutions/passed/024.md
|
||||
- "Stalled":
|
||||
- federation/resolutions/stalled/013.md
|
||||
- "In Progress":
|
||||
- federation/resolutions/in-progress/025.md
|
||||
- federation/resolutions/in-progress/026.md
|
||||
- "Minutes":
|
||||
- federation/minutes/index.md
|
||||
- "Recently":
|
||||
- federation/minutes/2024-08-15.md
|
||||
- federation/minutes/2024-04-17.md
|
||||
- federation/minutes/2024-03-29.md
|
||||
- "Archive":
|
||||
@ -144,19 +132,39 @@ nav:
|
||||
- federation/minutes/2022-03-03.md
|
||||
- federation/minutes/2023-05-03.md
|
||||
- "Digital Tools": federation/tools.md
|
||||
- "Funding applications":
|
||||
- federation/funding-applications/index.md
|
||||
- federation/funding-applications/culture-of-solidarity.md
|
||||
- federation/funding-applications/ford-foundation.md
|
||||
- federation/funding-applications/private-funder.md
|
||||
- federation/funding-applications/sovereign-tech-fund.md
|
||||
- federation/funding-applications/user-operated-internet.md
|
||||
- "Abra":
|
||||
- abra/index.md
|
||||
- "Install": abra/install.md
|
||||
- "Quick Start": abra/quickstart.md
|
||||
- "Upgrade": abra/upgrade.md
|
||||
- "Design": abra/design.md
|
||||
- "Recipes": abra/recipes.md
|
||||
- "Hack": abra/hack.md
|
||||
- "Troubleshoot": abra/trouble.md
|
||||
- "Cheat Sheet": abra/cheat-sheet.md
|
||||
- "Specifications":
|
||||
- specs/index.md
|
||||
- "Backups":
|
||||
- specs/backup/index.md
|
||||
- specs/backup/maintain.md
|
||||
- specs/backup/spec.md
|
||||
- "Glossary":
|
||||
- glossary/index.md
|
||||
|
||||
plugins:
|
||||
- awesome-pages
|
||||
- search
|
||||
- redirects:
|
||||
redirect_maps:
|
||||
"get-involved/support/index.md": intro/support.md
|
||||
|
||||
repo_name: coop-cloud/docs.coopcloud.tech
|
||||
repo_url: https://git.coopcloud.tech/coop-cloud/docs.coopcloud.tech/
|
||||
repo_name: toolshed/docs.coopcloud.tech
|
||||
repo_url: https://git.coopcloud.tech/toolshed/docs.coopcloud.tech/
|
||||
edit_uri: _edit/main/docs/
|
||||
|
||||
extra_css:
|
||||
|
@ -1,15 +1,15 @@
|
||||
markdown~=3.2
|
||||
mkdocs~=1.6.1
|
||||
|
||||
mkdocs~=1.5.3
|
||||
mkdocs-material~=9.5.7
|
||||
mkdocs-material-extensions~=1.3.1
|
||||
mkdocs-awesome-pages-plugin==2.9.2
|
||||
pygments~=2.16
|
||||
pymdown-extensions~=10.2
|
||||
mkdocs-material==9.5.49
|
||||
mkdocs-material-extensions==1.3.1
|
||||
mkdocs-awesome-pages-plugin==2.10.1
|
||||
pygments==2.19.1
|
||||
pymdown-extensions==10.14
|
||||
mkdocs-redirects==1.2.2
|
||||
|
||||
# Requirements for plugins
|
||||
babel~=2.10
|
||||
colorama~=0.4
|
||||
paginate~=0.5
|
||||
babel==2.16.0
|
||||
colorama==0.4.6
|
||||
paginate==0.5.7
|
||||
regex>=2022.4
|
||||
requests~=2.26
|
||||
requests==2.32.3
|
||||
|
Reference in New Issue
Block a user