coop-cloud/docs.coopcloud.tech
coop-cloud
/
docs.coopcloud.tech
4
1
Fork 14
Code Issues Pull Requests 2 Releases Activity

Drop $ for better copy/pasta
continuous-integration/drone/push Build is passing Details 

Closes https://git.autonomic.zone/coop-cloud/docs.coopcloud.tech/issues/7.
This commit is contained in:
decentral1se 2021-05-31 21:52:33 +02:00
parent cfd56facc3
commit 219a5e665b
No known key found for this signature in database
GPG Key ID: 92DAD76BD9567B8A
5 changed files with 37 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
docs/app-config-guide.md
View File

@ -116,7 +116,7 @@ Here is an example CSS config which hides the local login and makes space for a
We normally do something like the following. We normally do something like the following.
```bash ```bash
$ ssh-keygen -t ed25519 -C drone@swarm.autonomic.zone ssh-keygen -t ed25519 -C drone@swarm.autonomic.zone
``` ```
When you're loading them into Drone, make sure to use the right name of the organisation when using `drone orgsecret add`. When you're loading them into Drone, make sure to use the right name of the organisation when using `drone orgsecret add`.
@ -126,16 +126,16 @@ When you're loading them into Drone, make sure to use the right name of the orga
First, get your Drone CLI tool downloaded and the environment configured. First, get your Drone CLI tool downloaded and the environment configured.
```bash ```bash
$ export DRONE_SERVER=https://drone.example.com export DRONE_SERVER=https://drone.example.com
$ export DRONE_TOKEN=$(pass show your-pass-store-path) export DRONE_TOKEN=$(pass show your-pass-store-path)
$ curl -L https://github.com/drone/drone-cli/releases/latest/download/drone_linux_amd64.tar.gz | tar zx curl -L https://github.com/drone/drone-cli/releases/latest/download/drone_linux_amd64.tar.gz | tar zx
``` ```
Then you can do things like: Then you can do things like:
``` ```
$ ./drone orgsecret ls ./drone orgsecret ls
$ ./drone orgsecret add someorg my_deploy_key @my_private_key_file ./drone orgsecret add someorg my_deploy_key @my_private_key_file
``` ```
#### How to enable build failure notifications #### How to enable build failure notifications

47
docs/config.md
View File

@ -7,13 +7,13 @@ Co-op Cloud stores per-app configuration in the `$USER/.abra/servers` directory,
The format of these configuration files is the same environment variable syntax used by Docker (with the `env_file:` statement in a `docker-compose.yml` file, or the `--env-file` option to `docker run`) and `direnv`: The format of these configuration files is the same environment variable syntax used by Docker (with the `env_file:` statement in a `docker-compose.yml` file, or the `--env-file` option to `docker run`) and `direnv`:
``` ```
$ abra app example_wordpress config abra app example_wordpress config
TYPE=wordpress TYPE=wordpress
DOMAIN=wordpress.example.com DOMAIN=wordpress.example.com
## Domain aliases ## Domain aliases
EXTRA_DOMAINS=', `www.wordpress.example.com`' EXTRA_DOMAINS=', `www.wordpress.example.com`'
LETS_ENCRYPT_ENV=production LETS_ENCRYPT_ENV=production
... ...
``` ```
@ -51,18 +51,18 @@ git commit -m "Initial import"
!!! warning "Test your revision-control self-discipline" !!! warning "Test your revision-control self-discipline"
`abra` does not yet help keep your app definitions are up-to-date. `abra` does not yet help keep your app definitions are up-to-date.
Make sure to run `git add` / `git commit` after making configuration changes, and `cd ~/.abra/servers && git pull` before running `abra app...` commands. Make sure to run `git add` / `git commit` after making configuration changes, and `cd ~/.abra/servers && git pull` before running `abra app...` commands.
Patches to add some safety checks and auto-updates would be very welcome! 🙏 Patches to add some safety checks and auto-updates would be very welcome! 🙏
## Collaborating with multiple teams ## Collaborating with multiple teams
In a more complex situation, where you're using Co-op Cloud to manage several servers, and you're collaborating with different people on different servers, you can set up **a separate repository for each subdirectory in `~/.abra/servers`**, or even a mixture of single-server and multi-server repositories: In a more complex situation, where you're using Co-op Cloud to manage several servers, and you're collaborating with different people on different servers, you can set up **a separate repository for each subdirectory in `~/.abra/servers`**, or even a mixture of single-server and multi-server repositories:
``` ```
$ ls -l ~/.abra/servers ls -l ~/.abra/servers
# Example.com's own app configuration: # Example.com's own app configuration:
lrwxrwxrwx. 1 user user 49 Oct 30 22:42 swarm.example.com -> /home/user/Example/coop-cloud-apps/swarm.example.com lrwxrwxrwx. 1 user user 49 Oct 30 22:42 swarm.example.com -> /home/user/Example/coop-cloud-apps/swarm.example.com
# Configuration for one of Example.com's clients – part of the same repository: # Configuration for one of Example.com's clients – part of the same repository:
@ -77,29 +77,30 @@ We don't have a public example of this yet, but something like this should do th
1. Save this as `Makefile` in your repository: 1. Save this as `Makefile` in your repository:
``` ```
# -s symlink, -f force creation, -F don't create symlink in the target dir # -s symlink, -f force creation, -F don't create symlink in the target dir
link: link:
@mkdir -p ~/.abra/servers/ @mkdir -p ~/.abra/servers/
@for SERVER in $$(find -maxdepth 1 -type d -name "[!.]*"); do \ @for SERVER in $$(find -maxdepth 1 -type d -name "[!.]*"); do \
echo ln -sfF "$$(pwd)/$${SERVER#./}" ~/.abra/servers/ ; \ echo ln -sfF "$$(pwd)/$${SERVER#./}" ~/.abra/servers/ ; \
ln -sfF "$$(pwd)/$${SERVER#./}" ~/.abra/servers/ ; \ ln -sfF "$$(pwd)/$${SERVER#./}" ~/.abra/servers/ ; \
done done
``` ```
This will set up symlinks from each directory in your repository to a correspondingly-named directory in `~/.abra/servers` – if your repository has a `swarm.example.com` directory, it'll be linked as `~/.abra/servers/swarm.example.com`.
This will set up symlinks from each directory in your repository to a correspondingly-named directory in `~/.abra/servers` – if your repository has a `swarm.example.com` directory, it'll be linked as `~/.abra/servers/swarm.example.com`.
2. Tell your collaborators (e.g. in the repository's `README`), to run `make` in their repository check-out. 2. Tell your collaborators (e.g. in the repository's `README`), to run `make` in their repository check-out.
!!! warning "You're on your own!" !!! warning "You're on your own!"
As with the [simple repository set-up above](#version-control), `abra` doesn't yet help you update your version control system when you make changes, nor check version control to make sure you have the latest configuration. As with the [simple repository set-up above](#version-control), `abra` doesn't yet help you update your version control system when you make changes, nor check version control to make sure you have the latest configuration.
Make sure to `commit` and `push` after you make any configuration changes, and `pull` before running any `abra app...` commands. Make sure to `commit` and `push` after you make any configuration changes, and `pull` before running any `abra app...` commands.
## Even more granularity? ## Even more granularity?
The plain-text, file-based configuration format means that you could even keep the configuration for different apps on the same server in different repositories, e.g. having `git.example.com` configuration in a separate repository to `wordpress.example.com`, using per-file symlinks. The plain-text, file-based configuration format means that you could even keep the configuration for different apps on the same server in different repositories, e.g. having `git.example.com` configuration in a separate repository to `wordpress.example.com`, using per-file symlinks.
We don't currently recommend this, because it might set inaccurate expectations about the security model – remember that, by default, **any user who can deploy apps to a Docker Swarm can manage *any* apps in that swarm**. We don't currently recommend this, because it might set inaccurate expectations about the security model – remember that, by default, **any user who can deploy apps to a Docker Swarm can manage _any_ apps in that swarm**.
[symlink]: https://en.wikipedia.org/wiki/Symlink [symlink]: https://en.wikipedia.org/wiki/Symlink

5
docs/credits.md
View File

@ -2,9 +2,8 @@
title: Credits & thanks title: Credits & thanks
--- ---
_The real Co-op Cloud was the friends we made along the way 🌠_ > _The real Co-op Cloud was the friends we made along the way 🌠_
Special thanks to: Special thanks to:
- [Doop Coop](mailto:cluck@doop.coop), for making a transparent version of the - [Doop Coop](mailto:cluck@doop.coop), for making a transparent version of the Co-op Cloud logo, and helping with OSX alpha testing.
Co-op Cloud logo, and helping with OSX alpha testing.

4
docs/package.md
View File

@ -12,8 +12,8 @@ Let's take as an example, [Matomo web analytics](https://matomo.org/).
I'm feeling lazy so, luckily for me, Matomo already has an example compose file in their repository! Let's download and edit it: I'm feeling lazy so, luckily for me, Matomo already has an example compose file in their repository! Let's download and edit it:
``` ```
$ mkdir matomo && cd matomo mkdir matomo && cd matomo
$ wget https://raw.githubusercontent.com/matomo-org/docker/master/.examples/apache/docker-compose.yml -O compose.yml wget https://raw.githubusercontent.com/matomo-org/docker/master/.examples/apache/docker-compose.yml -O compose.yml
``` ```
Open the `compose.yml` in your favourite editor and have a gander :swan: . There are a few things we're looking for -- full list to come -- but a few things we can immediately see are: Open the `compose.yml` in your favourite editor and have a gander :swan: . There are a few things we're looking for -- full list to come -- but a few things we can immediately see are:

6
docs/secrets.md
View File

@ -7,7 +7,7 @@ title: Managing secret data
Co-op Cloud uses [Docker Secrets] to handle sensitive data, like database passwords and API keys, securely: Co-op Cloud uses [Docker Secrets] to handle sensitive data, like database passwords and API keys, securely:
``` ```
$ DOCKER_CONTEXT=swarm.example.com docker secret ls DOCKER_CONTEXT=swarm.example.com docker secret ls
example_mediawiki_db_password_v1 example_mediawiki_db_password_v1
example_wordpress_db_password_v1 example_wordpress_db_password_v1
``` ```
@ -27,7 +27,7 @@ You will notice `v1` in the example secret names above: like Docker Configs, Doc
Because secret versions are managed per-instance by the people deploying their apps, secret versions are stored in the `.env` file for each app: Because secret versions are managed per-instance by the people deploying their apps, secret versions are stored in the `.env` file for each app:
``` ```
$ find -L ~/.abra/servers/ -name '*.env' -print0 | xargs -0 grep -h SECRET find -L ~/.abra/servers/ -name '*.env' -print0 | xargs -0 grep -h SECRET
OIDC_CLIENT_SECRET_VERSION=v1 OIDC_CLIENT_SECRET_VERSION=v1
RPC_SECRET_VERSION=v1 RPC_SECRET_VERSION=v1
CLIENT_SECRET_VERSION=v1 CLIENT_SECRET_VERSION=v1
@ -37,7 +37,7 @@ CLIENT_SECRET_VERSION=v1
If you try and add a secret version which already exists, Docker will helpfully complain: If you try and add a secret version which already exists, Docker will helpfully complain:
``` ```
$ abra app example_wordpress secret insert db_password v1 foobar abra app example_wordpress secret insert db_password v1 foobar
Error response from daemon: rpc error: code = AlreadyExists desc = secret example_wordpress_db_password_v1 already exists Error response from daemon: rpc error: code = AlreadyExists desc = secret example_wordpress_db_password_v1 already exists
``` ```