So, if you’ve followed along, you’re well on your way to operating your own coop-cloud! We’re now going to dive into a bit of software and command line usage. This will be a more verbose discussion of what the new operator tutorial says, so if ssh and command line Linux use is familiar to you, you may just want to go there. The rest of this text hopefully gives you the basics and ways to read more when needed. Again, if you’re setting this up for multiple people, be aware that you may need additional Linux skills down the line to fix issues that may arise during upgrades – make sure you have these if you’re putting life-essential things in your coop-cloud (such as using it as your password manager instead of a cloud service like LastPass).
The coop-cloud uses a tool called abra as a core tool for operators. The idea is that you can do most you need to do with apps (starting, configuring, deploying, upgrading, …) through there. The apps are then the things running on your cloud – such as nextcloud or this blog. Remember, clouds are just computers – in this case, it is the server you’ve set up. You can use abra on the server that runs your apps, but it is designed for use on the system you use every day (we’ll call this workstation). That means you’ll have your configuration on your workstation (and possibly on other peoples’ workstation, if you jointly manage the server).
SSH remote login
In short:
ssh-keygen
ssh-copy-id -i /path/to/key <server-user>@<server-domain>
Then add the following to your ~/.ssh/config:
Host <server-domain>
User <server-user>
IdentityFile /home/<username>/.ssh/my-coopcloud
PasswordAuthentication no
Use this to only type your passphrase once:
eval `ssh-agent`
ssh-add
To do this remote management, it uses ssh – most operating systems (though not Windows) come with it. The operator tutorial kinda skips over this, but you’ll want to set up an ssh key and use ssh-agent. Before the step-by-step guide, here’s a brief summary of why and how. Such a login is slightly more secure, but more importantly, it saves you from needing to type your password every time. It works by using a public key (which you’ll copy to the server) and a corresponding private key (which is the secret bit, like your password). When you log in, cryptography is used in such a way that the private key never leaves your computer (unlike with a password). This also means anyone with the private key can log in – this is why it is protected by a passphrase (which is just another name for a password). ssh-agent then allows you to type your password once and use your key until you close your terminal.
You’ll (at least) need your server’s domain name, a user on your server and ssh running on your server. An explanation can be found here. If running on a home network, make sure port forwarding for ssh is set up (see linked tutorials in the networking section in an earlier post).
Side-Note: The coop-cloud operator tutorial assumes you also manage your server remotely. If you don’t want to expose your server to logins from the internet, you can usually just set a name in the /etc/hostname file on your server while you set it up, by putting something like my-coop-cloud in that file – on most local networks, that “just works”, and you can log in to your server from your workstation by using this as the domain name, but be aware that some abra commands will complain later on; use the -D or —no-domain-checks option to circumvent that.
First, we create a key, by running:
ssh-keygen
This will create a key with the default settings. It will ask you where to store it (I recommend using a name like /home/<username>/.ssh/my-coopcloud) and then a passphrase. You can leave that field empty and not have one, but: use a passphrase. Your private key will then be the /home/<username>/.ssh/my-coopcloud and the public key will be the file /home/<username>/.ssh/my-coopcloud.pub. Now copy your key to the server (replace <server-user> with the user on your server and <server-domain> with your server’s domain). You’ll still need your password here.
ssh-copy-id -i /home/<username>/.ssh/my-coopcloud.pub <server-user>@<server-domain>
Side-note: many tutorials will have you manually copy the file over and add it in ~/.ssh/authorized_keys; ssh-copy-id does the same, just all in one command.
On your workstation, you can now add set following configuration:
Host <server-domain>
User <server-user>
IdentityFile /home/<username>/.ssh/my-coopcloud
PasswordAuthentication no
If you put this in the file /home/<username>/.ssh/config, future logins will work as:
ssh <server-domain>
However, you still need to enter the passphrase of your key. To save you the trouble, use these commands to load your key:
eval `ssh-agent`
ssh-add
After you enter your passphase, your key will now be used automatically.
Explanation: the command ssh-agent generates a few lines of code; the `` tell your command prompt to give this code to the eval command, which then executes that code. Understanding the exact functionality requires background on linux sockets and process management, but if you’re interested, check out the manual. There are also ways to make sure the ssh-agent runs as soon as you log in to your workstation (this answer either by adding some code to the startup of your command line in ~/.bashrc or via systemd). Then you’ll just need ssh-add and it will work in all your command lines.
Especially if you’re managing your server via the internet, I recommend disabling password authentication. Before you do this, consider making a backup of your key (or have some other way of connecting to the server without ssh, for example, by connecting a keyboard and a monitor). If you read the configuration above, you might have noticed the line that says PasswordAuthentication no – this tells your workstation to not use password authentication when talking to your server. To tell your server never to accept passwords, you’ll need to update the configuration on the server. The configuration file on the server is normally /etc/ssh/sshd_config and in it you can disable password authentication by finding these lines and removing the # at the start of the second line:
# Change to no to disable tunnelled clear text passwords
#PasswordAuthentication no
You’ll need to restart your sshd, which can be specific to the Linux distribution you installed. Typically:
systemctl restart sshd
Side-note: the “d” in sshd refers to “daemon” and means background service – it is the software that accepts the connection when you type ssh <server-domain> on your workstation. This is a common pattern throughout the Linux-world. There are many more configurations you can make that further help security, but for this you’re better off looking at a dedicated tutorial for sshd. But don’t worry – most Linux distributions provide a reasonably secure default configuration.
Set up docker
The tutorial gives you a pretty concise way to set up everything you need. However, as it points out, curl https://get.docker.com | bash is not the recommended way for long-term use. The official docker installation guide has an overview for various operating systems. I recommend relying on the package manager and install docker as part of your Linux installation process (I’ll probably one day update that blog to explain a simple installation). The guide also tells you to set up docker swarm and create two networks for it – these will be used to make sure all your apps are talked to over a single special app called a proxy. The proxy is software that enables you to run multiple apps on the same port. Finally, it recommends that you add your server user to the group docker, which allows this user to use docker commands. Remember that this means anyone that can log in as this user can manage all your apps and (with a bit of hacker wizardry) access all your data. This is why the passphrase for your ssh key is important.
Installing abra
There are a couple of ways to install abra – the script method in the guide is “good enough”, an overview is here. Setting up autocomplete might sound like a hassle, but it’s not that complicated and makes our life way easier. After that, getting abra to talk to your server is as easy as:
abra server add <server-domain>
If you’re not connecting to your server via the internet and your server domain is something like my-coopcloud, make sure to use that name here. The guide recommends against this, but at least in my experience, it still works.
Before we move on to the web proxy setup, I recommend setting up versioning for all your apps. This works as follows (on your workstation):
cd ~/.abra/server/<server-domain>
git init
touch README.md
git add .
git commit -m “empty configuration”
If you’ve never used git before, it will tell you to provide an e-mail address and name – you can use anything you want (you’ll need to repeat the last line afterwards). You can share this repository with anyone else managing the server, or make a backup. There’s a lot to learn about git, but if you don’t want to care about that, just remember to do the following whenever you change the configuration of the server:
cd ~/.abra/server/<server-domain>
git add .
git commit -m “<a summary of your change>”
The reason this is useful is that if something goes wrong, while you’re making the change, you can go to this folder and reset to the last time you made a change (this will discard all changes!):
cd ~/.abra/server/<server-domain>
git restore .
Note that this only applies to the files located in .abra/server/<server-domain>; it can’t be used to repair errors on the server itself.
Your first app: traefik and nextcloud
Now we’re ready to run your first app on your personal coop-cloud! As mentioned, we’ll use a proxy so that you can deploy multiple apps without lots of hassle. The proxy is called traefik and the setup is as easy as this, where is a sub-domain of your coop-cloud (for example, traefik.my-coopcloud):
abra app new traefik
abra app config <traefik-domain>
abra app deploy <traefik-domain>
As the guide notes, the config step will open an editor that allows you to configure your proxy. Setting up nextcloud works almost the same way:
abra app new nextcloud --secrets
abra app config <nextcloud-domain>
abra app deploy <nextcloud-domain>
The first line is different, because the nextcloud app has secrets that should not be stored in a configuration file. Make a habit of storing these in a secure way. In many cases you can read them from your container via abra app run <nextcloud-domain> app -- cat /run/secrets/admin_password, but try not to make a habit of it, because it is not guaranteed to work everywhere. For an in-depth overview of secrets, check out the docker manual; if you store your secrets carefully, you probably won’t need this page, though.
By the way: traefik and nextcloud are recipes, they’re used via abra app new <recipe> and you’ll find information about their requirements at the recipes page. Now you can go crazy and set up all the apps you want. However, you’ll also want to actually use the app!
Administrating your new nextcloud service
If you’re not familiar – nextcloud is a package that lets you synchronize files, but there are also many other plugins (such as calendars and a simple task manager), which can be installed from github. Both the installation of plugins and the creation of accounts happens via nextcloud’s admin interface – this is a common pattern in the coop cloud — deploy an app and then configure it. For nextcloud, just open a browser and go to <nextcloud-domain> with your admin password from above. The standard admin username is admin, if you did not change it during abra app config (the variable name is ADMIN_USER; if you’re not sure, whether you changed it, just run abra app config <nextcloud-domain> again).