HOPE Co-op Cloud Operators Tutorial

Welcome!

This tutorial is a modification of the new operators tutorial in the Co-op Cloud docs. We recommend you read through other parts of those docs now or later if you have questions!

Deploy your first app

In order to deploy an app today you'll need:

1. A GNU/Linux, MacOS, or WSL system
2. An index card with credentials and a domain

For this workshop a server has already been set up and docker swarm initialized, but no apps have been deployed, this is your task.

SSH configuration

abra relies on ssh being configured to a default key and username, in practice, we need for ssh <server-domain> to successfully connect us to our server, with no password prompt.

In order to configure this, you will have to generate an SSH key for to use for the server:

If you so desire, reusing an existing SSH key will not break any later steps

# generate your ssh keypair at ~/.ssh/id_hope_2026
ssh-keygen -t ed25519 -f ~/.ssh/id_hope_2026

We recommend against password protecting your key, many ssh connections need to be opened which would each require your password to be entered.

# look for the files id_hope_2026 and id_hope_2026.pub
ls ~/.ssh

Now, you'll want to move the public key to the server.

# copy the public key to the server's authorized keys

ssh-copy-id -i ~/.ssh/id_hope_2026 root@<server-domain>

# check if it worked

ssh root@<server-domain> -i ~/.ssh/id_hope_2026

Finally, we want the server hostname to automatically resolve and use our key, so we want to edit ~/.ssh/config

# ~/.ssh/config
nano ~/.ssh/config

You should add an entry like this

Host <server-domain>
  User root
  IdentityFile ~/.ssh/id_hope_2026

Finally make sure it works

ssh <server-domain>

If things still aren't working, see the abra SSH troubleshooting for a working SSH configuration example or use abra server add -h for the help output.

Beware of SSH dragons

Under the hood abra uses plain 'ol ssh and aims to make use of your existing SSH configurations in ~/.ssh/config and interfaces with your running ssh-agent for password protected secret key files.

Running server add with -d or --debug should help you debug what is going on under the hood. ssh -v ... should also help. If you're running into SSH connection issues with abra take a moment to read this troubleshooting entry.

Server configuration

For this workshop, we've configured Docker on the host machine already, so you can skip this section. We've kept a link to the instructions below if you want to read through the setup: https://docs.coopcloud.tech/operators/tutorial/#server-configuration

DNS setup

For this workshop, we've already set up DNS records, so you can access your server based on the provided domain. We kept a link to the information below if you want to read through the setup: https://docs.coopcloud.tech/operators/tutorial/#dns-setup

Install abra

Now we can install abra locally on your machine and hook it up to your server. We support a script-based installation method (script source). This is to be run on your own machine, so if you still are in an ssh session, type exit to get back to your local shell:

curl https://install.abra.coopcloud.tech | bash

The installer will verify the downloaded binary checksum. If you prefer, you can manually verify the binary, and then manally place it in one the directories in your $PATH variable. To validate that everything is working try listing the --help command or -h to view output:

abra -h

You may need to add the ~/.local/bin/ directory to your $PATH variable, in order to run the executable. You can edit your path variable either in ~/.profile or in ~/.bashrc or something similar.

Add export PATH=$PATH:$HOME/.local/bin to the bottom of the file so ~/.local/bin/ will be in your path next time you open the terminal. You can also load the new profile immediately with the commands below

source ~/.profile
or
source ~/.bashrc

If you run into issues during installation, please talk to an instructor

Set up autocomplete

Most abra commands require typing the fully qualified domain name for your app, so we highly recommend configuring command-line auto-completion. See abra autocomplete -h for more on how to do this. The instructions vary depending on which shell you use.

With autocomplete enabled, you can run a command like abra app deploy myapp.example.com by just typing abra app deploy myapp<tab>.

Add your server

Now you can connect abra with your server. You must have a working SSH configuration for your server before you can proceed. That means you can run ssh <server-domain> (<server-domain> refers to the domain name, not the ip address) on your command-line and everything Works .

ssh <server-domain> hostname -I # make sure it works
abra server add <server-domain>

It is important to note that <server-domain> here is a publicly accessible domain name which points to your server IP address. abra does make sure this is the case and this is done to avoid issues with HTTPS certificate rate limiting.

Can I use arbitrary server names?

Yes, this is possible. You need to ensure that your Host ... entry in your SSH configuration includes the name. So, for example, in ~/.ssh/config:

  Host example.com example
    ...

And then:

abra server add example

You will now have a new ~/.abra/ folder on your local file system which stores all the configuration of your Co-op Cloud instance.

By now abra should have registered this server as managed. To confirm this run:

abra server ls

How do I share my configs in ~/.abra?

It's possible and relatively easy, for more see this handbook entry. Git skills are generally required.

Web proxy setup

In order to have your Co-op cloud deployment serve the public internet, we need to install the core web proxy, Traefik.

Traefik is the main entrypoint for all web requests (e.g. like NGINX) and supports automatic SSL certificate configuration and other quality-of-life features which make deploying libre apps more enjoyable.

You need to keep port :80 and :443 free on your server for web proxying to your apps. Typically, you don't need to keep any other ports free as the core web proxy keeps all app ports internal to its network. Sometimes however, you need to expose an app port when you need to use a transport which would perform better or more reliably without proxying.

Do you support multiple web proxies?

Yes, this is possible. See this handbook entry for more. Be warned, this is a relatively advanced topic.

1. To get started, you'll need to create a new app:

abra app new traefik

Choose your newly registered server and specify a domain name. By default abra will suggest <app-name>.<your-server> or prompt you with a list of servers.

Should I use www for traefik?

Generally no. No one will be directly accessing the traefik domain name unless they want to see the traefik dashboard. You should reserve the www or apex domains for apps like custom-html which let you host sites. Traefik is just a proxy to other apps!

2. Configure this new traefix app

You will want to take a look at your generated configuration and update the placeholder LETS_ENCRYPT_EMAIL value, used by Let's Encrypt to manage SSL certificates. This placeholder must be updated for traefik to deploy correctly. You can do that by running abra app config:

abra app config <traefik-domain>

Every app you deploy will have one of these .env files, which contains variables which will be injected into app configurations when deployed. These files exist at relevantly named path:

~/.abra/servers/<domain>/<traefik-domain>.env

Variables starting with # are optional, others are required. Some things to consider here is that by default our Traefik recipe exposes the metric dashboard unauthenticated on the public internet at the URL <traefik-domain> it is deployed to, which while helpful for debugging, is not ideal in production environments. You can disable this with:

DASHBOARD_ENABLED=false

3. Now it is time to deploy your app:

abra app deploy <traefik-domain>

Voila. Abracadabra your first app is deployed

Deploy Nextcloud

And now we can deploy apps. Let's create a new Nextcloud app.

abra app new nextcloud --secrets

The -S or --secrets flag is used to generate secrets for the app: database connection password, root password and admin password.

Beware of password dragons

Take care, these secrets are only shown once on the terminal so make sure to take note of them! abra makes use of the Docker secrets mechanism to ship these secrets securely to the server and store them as encrypted data. Only the apps themselves have access to the values from here on, they're placed in /run/secrets on the container file system.

Now we can deploy Nextcloud:

abra app deploy <nextcloud-domain>

abra app deploy will wait nearly a minute for an app to deploy until it times out and shows some helpful commands for how to debug what is going on. If things don't come up in time, try running the following:

abra app ps -w <nextcloud-domain>     # status check
abra app logs <nextcloud-domain>      # logs trailing

Your new traefik instance will detect that a new app is coming up and generate TLS certificates for it. You can see what traefik is up to using the same commands above but replacing <nextcloud-domain> with the <traefik-domain> you chose earlier (abra app ls will remind you what domains you chose ).

Upgrades

You can check if any of your deployed apps have updates available with:

abra app ls -S

To upgrade an app to the newest available version run:

abra app upgrade <nextcloud-domain>

Finishing up

Hopefully you got something running! Well done! The Recipies Index would probably be the next place to go, take a look at the apps available to be deployed!

Or, continue learning more about what abra can do by checking out the Operators Handbook!

If you don't see something on the recipes list or wish that a project were updated more often, you should explore the side of coop-cloud that is recipe maintanence! And, continue on to the next section: Next Steps