diff --git a/docs/app-config-guide.md b/docs/app-config-guide.md index 1bb5b7c..fb719b3 100644 --- a/docs/app-config-guide.md +++ b/docs/app-config-guide.md @@ -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. ```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`. @@ -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. ```bash -$ export DRONE_SERVER=https://drone.example.com -$ 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 +export DRONE_SERVER=https://drone.example.com +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 ``` Then you can do things like: ``` -$ ./drone orgsecret ls -$ ./drone orgsecret add someorg my_deploy_key @my_private_key_file +./drone orgsecret ls +./drone orgsecret add someorg my_deploy_key @my_private_key_file ``` #### How to enable build failure notifications diff --git a/docs/config.md b/docs/config.md index 315402c..662fd8e 100644 --- a/docs/config.md +++ b/docs/config.md @@ -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`: ``` -$ abra app example_wordpress config -TYPE=wordpress - +abra app example_wordpress config +TYPE=wordpress + DOMAIN=wordpress.example.com -## Domain aliases -EXTRA_DOMAINS=', `www.wordpress.example.com`' -LETS_ENCRYPT_ENV=production +## Domain aliases +EXTRA_DOMAINS=', `www.wordpress.example.com`' +LETS_ENCRYPT_ENV=production ... ``` @@ -51,18 +51,18 @@ git commit -m "Initial import" !!! 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 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: 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: @@ -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: - ``` - # -s symlink, -f force creation, -F don't create symlink in the target dir - link: - @mkdir -p ~/.abra/servers/ - @for SERVER in $$(find -maxdepth 1 -type d -name "[!.]*"); do \ - echo ln -sfF "$$(pwd)/$${SERVER#./}" ~/.abra/servers/ ; \ - ln -sfF "$$(pwd)/$${SERVER#./}" ~/.abra/servers/ ; \ - 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`. + ``` + # -s symlink, -f force creation, -F don't create symlink in the target dir + link: + @mkdir -p ~/.abra/servers/ + @for SERVER in $$(find -maxdepth 1 -type d -name "[!.]*"); do \ + echo ln -sfF "$$(pwd)/$${SERVER#./}" ~/.abra/servers/ ; \ + ln -sfF "$$(pwd)/$${SERVER#./}" ~/.abra/servers/ ; \ + 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`. 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!" - 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? 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 diff --git a/docs/credits.md b/docs/credits.md index b72859f..331169a 100644 --- a/docs/credits.md +++ b/docs/credits.md @@ -2,9 +2,8 @@ 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: - - [Doop Coop](mailto:cluck@doop.coop), for making a transparent version of the - Co-op Cloud logo, and helping with OSX alpha testing. +- [Doop Coop](mailto:cluck@doop.coop), for making a transparent version of the Co-op Cloud logo, and helping with OSX alpha testing. diff --git a/docs/package.md b/docs/package.md index 5dd1da9..776d721 100644 --- a/docs/package.md +++ b/docs/package.md @@ -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: ``` -$ mkdir matomo && cd matomo -$ wget https://raw.githubusercontent.com/matomo-org/docker/master/.examples/apache/docker-compose.yml -O compose.yml +mkdir matomo && cd matomo +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: diff --git a/docs/secrets.md b/docs/secrets.md index bfcc536..186096e 100644 --- a/docs/secrets.md +++ b/docs/secrets.md @@ -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: ``` -$ DOCKER_CONTEXT=swarm.example.com docker secret ls +DOCKER_CONTEXT=swarm.example.com docker secret ls example_mediawiki_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: ``` -$ 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 RPC_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: ``` -$ 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 ```