From 8dabfac8975d1cde6b7eac374b6b7e58f44f1f4f Mon Sep 17 00:00:00 2001 From: decentral1se Date: Wed, 2 Feb 2022 21:27:05 +0100 Subject: [PATCH] more focus on abra --- docs/abra/index.md | 1 + docs/abra/quickstart.md | 15 +++++++++++++++ docs/abra/trouble.md | 6 ++++++ docs/index.md | 2 ++ docs/operators/tutorial.md | 10 ++++++++-- mkdocs.yml | 1 + 6 files changed, 33 insertions(+), 2 deletions(-) create mode 100644 docs/abra/quickstart.md diff --git a/docs/abra/index.md b/docs/abra/index.md index 319ab0a..90e682d 100644 --- a/docs/abra/index.md +++ b/docs/abra/index.md @@ -5,6 +5,7 @@ title: Abra `abra` is our flagship client & command-line tool which 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 :heart: - [Install](/abra/install): You want to install `abra` :100: +- [Quick start](/abra/quickstart): You're ready to get started using `abra` :muscle: - [Upgrade](/abra/upgrade): You're looking for instructions on how to upgrade `abra` :arrow_heading_up: - [Hack](/abra/hack): You wan to hack on `abra` and help out with the development :woman_construction_worker: - [Troubleshoot](/abra/troubleshoot): `abra` ain't working and you'd like to know why :boom: diff --git a/docs/abra/quickstart.md b/docs/abra/quickstart.md new file mode 100644 index 0000000..90fb553 --- /dev/null +++ b/docs/abra/quickstart.md @@ -0,0 +1,15 @@ +--- +title: Quick start +--- + +Once you've got `abra` installed, you can start your own Co-op Cloud deployment. + +The core features of `abra` allow you to create, deploy and maintain libre software apps. `abra` can help you do on existing servers or by creating new servers (supported: [Servers.coop](https://servers.coop/) & [Hetzner](https://hetzner.com)), manage your DNS configuration (supported: [Gandi](https://gandi.net)) and maintain recipes. + +There are a few ways to get started, here are some entrypoints listed below: + +- If you're new around here and you'd like to learn how to deploy apps with `abra`, then a good place to start is the [new operators tutorial](/operators/tutorial). If you've already deployed some apps and would like to learn how to maintain them, then the [operators handbook](/operators/handbook) is the right place. + +- If you're installing `abra` so you can do recipe packaging, take a look at the [new maintainers tutorial](/maintainers/tutorial). `abra` can help you check the quality of the recipe you've packaged and help you publish it to the public recipe catalogue. Then others can deploy your configuration :rocket: + +If you run into any issues, please see the [troubleshooting page](/abra/trouble) :bomb: diff --git a/docs/abra/trouble.md b/docs/abra/trouble.md index 6cbec98..18a7407 100644 --- a/docs/abra/trouble.md +++ b/docs/abra/trouble.md @@ -2,6 +2,12 @@ title: Troubleshoot --- +## Where do I report `abra` bugs / feature requests? + +## I'm having a bad day, where do I find a human? + +TODO. + ## SSH connection issues? TODO. diff --git a/docs/index.md b/docs/index.md index 096afe0..fbe0345 100644 --- a/docs/index.md +++ b/docs/index.md @@ -26,6 +26,8 @@ We'd be happy to hear feedback about our documentation, if it was helpful, what - [Recipes](/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: - [Glossary](/glossary/): You'd like clarification about project terminology :book: diff --git a/docs/operators/tutorial.md b/docs/operators/tutorial.md index 0f2966d..f12f95c 100644 --- a/docs/operators/tutorial.md +++ b/docs/operators/tutorial.md @@ -66,6 +66,10 @@ Finally, with an app and deployment environment, we need a tool to read the reci ## Deploy your first app +> - TODO: explain how you can add an existing server with `abra` +> - TODO: explain how to you create a server with `abra` +> - TODO: explain what to keep in mind with a server, port 80/44, traefik proxy, docker runtime, etc. + In order to deploy an app you need two things: 1. a server (e.g. [Hetzner VPS](https://www.hetzner.com/cloud)), with 1. SSH access and 2. a public IP address @@ -90,7 +94,9 @@ Where `116.203.211.204` can be replaced with the IP address of your server. ### Bootstrap `abra` -You have two options for setting up your command-line client. You can install `abra` on your local development machine or remotely on the actual server. Please see +> TODO: this could come eariler, this could be the first step? You can create servers/manage DNS now with `abra`... + +You have two options for setting up your command-line client. You can install `abra` on your local development machine or remotely on the actual server. Please see Once your DNS and Docker daemon are up, you can install [`abra`](https://git.coopcloud.tech/coop-cloud/abra) locally on your developer machine and hook it up to your server. @@ -135,7 +141,7 @@ Where `example.com` is replaced with your server DNS name. abra server add -p example.com username 2222 ``` -The `-p` or `--provision` flag means that abra will initialise the [new single-host swarm](https://docs.docker.com/engine/swarm/key-concepts/) on your server. +The `-p` or `--provision` flag means that abra will initialise the [new single-host swarm](https://docs.docker.com/engine/swarm/key-concepts/) on your server. You will now have a new `~/.abra/` folder on your local file system which stores all the configuration of your Co-op Cloud instance. You can easily share this as a git repository with others. diff --git a/mkdocs.yml b/mkdocs.yml index 9c18cba..1c94fb2 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -61,6 +61,7 @@ nav: - "Abra": - abra/index.md - "Install": abra/install.md + - "Quick start": abra/quickstart.md - "Upgrade": abra/upgrade.md - "Hack": abra/hack.md - "Troubleshoot": abra/trouble.md