toolshed/docs.coopcloud.tech
toolshed/docs.coopcloud.tech
4
1
Fork 19
Code Issues 1 Pull Requests 1 Packages Releases Activity

docs: moar info on perms, formatting
All checks were successful
continuous-integration/drone/push Build is passing
Details

Browse Source
This commit is contained in:
decentral1se 2025-01-10 18:30:28 +01:00
parent e3a178e5fc
commit 4869031a10
Signed by: decentral1se
GPG Key ID: 03789458B3D0C410
1 changed files with 24 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

57
docs/abra/hack.md
View File

@ -8,6 +8,17 @@ Welcome to Hacking the Planet with `abra`! We're looking forward to see what you
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:
* [Toolshed](https://git.coopcloud.tech/org/toolshed/)
* [the recipes](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/toolshed/abra).
@ -21,7 +32,7 @@ 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/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.
@ -49,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 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:
@ -82,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
@ -103,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
@ -115,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
@ -146,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
@ -161,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.
@ -205,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