Ansible CryptPad

Features:

• 🚀 Effective deployment of CryptPad using Ansible
• 🏌️ Configuration of Caddy as reverse proxy in front of Nginx (see rationale below).
• 💆 Vagrant for ergonomic local development.

Tested on:

• Linux Mint 22.1
• Debian 12 running on Raspberry Pi 4

Motivation

I think CryptPad is a great project. With this Ansible project I want to make it even easier for developers to deploy their own CryptPad instances.

Running CryptPad locally on your machine

Be sure to install these first:

• Ansible
• Vagrant
  • Tip: Vagrant uses Virtualbox by default, but I recommend checking out Vagrant+Libvirt.

Steps:

1. Run git clone git@code.on.nilsnh.no:nilsnh/ansible-cryptpad.git to download this repo.

2. Start local Vagrant with vagrant up.

   • Use vagrant destroy to fully delete box.
   • Use vagrant ssh to ssh inside a running box.
   • Use vagrant provision to quickly re-run Ansible changes when developing.

3. After the playbook completes all its steps you should have a locally running cryptpad instance.

4. To actually visit the CryptPad service running inside Vagrant you'll need to update your hosts file:

   • Run ./get-vagrant-ip.sh to learn the IP address of your virtual machine.
   • See group_vars/all/main.yml to learn the domain addresses CryptPad is served from.
   • You'll need update your machine's hosts file so that both addresses resolve to Vagrant's IP.
   • Because Vagrant's IP can change over time there's an ansible playbook update-hosts-file.yml for updating your machine's host file. Run it by calling ansible-playbook --become --ask-become-pass update-hosts-file.yml.
   • ☝️ This command will prompt you for your sudo password. Read this file to see exactly what it does.

5. You should now be able to visit your CryptPad domain which is cryptpad.local by default.

6. When visiting CryptPad your browser will complain about Caddy's self-signed certificate

   • Run ansible-playbook --become --ask-become-pass trust-self-signed-ca-certificate.yml to trust Caddy's certificate authority (CA).
   • ☝️ This command will prompt you for your sudo password. Read this file to see exactly what it does.

7. After trusting the CA certificate, you should get no errors when visiting cryptpad.local in your browser.

8. Finally, you need to create an admin account.

   1. Run vagrant ssh to get inside the vm.
   2. Run sudo journalctl -u cryptpad to see CryptPad's logs. There you'll see a link for the admin setup.

Deploying to a real server

Prerequisites:

• You'll need a Linux server somewhere that you have ssh access and sudo privilege.

Steps:

1. Add your server to the ansible inventory file inventory/production.
2. Add another host entry for deploying to your server inside playbook.yml.
   • Update your playbook vars with some nice domains for your CryptPad instance.
   • Make sure that those domains actually resolve to your server's IP.
3. Call ansible-playbook --become playbook.yml.
4. After deployment Caddy will provision necessary SSL certificates, and your CryptPad will be available at your configured domain.
5. Finally, you need to create an admin account.
   1. Use ssh to get into your server.
   2. Run sudo journalctl -u cryptpad to see CryptPad's logs. There you'll see a link for the admin setup.
6. You've successfully deployed CryptPad, pat yourself on the back! ✨ And be sure to check out CryptPad's administrator guide.

Customizing your instance

Be sure to check out the guide on instance customization. See the file roles/cryptpad/defaults/main.yml to learn how we give users a link to the source code used to deploy this service.

Backing up your CryptPad

CryptPad stores its data as encrypted files, and they provide a guide on which files to backup. Personally, I run periodic backups using restic. But there are many other capable backup solutions out there.

Rationale: Why combine Caddy and Nginx?

My goto reverse proxy technology is Caddy, and other folks have their favorites. When I first tried to deploy CryptPad I learned that there were some community contributed reverse proxy configurations, including one for Caddy.

The community provided Caddy configuration was very extensive, it looked like it had been inspired by the official Nginx advanced configuration. After deploying this Caddy config I ran into issues with CryptPad which made me suspect that the advanced Nginx configuration had been developed further, resulting in subtle bugs caused by staleness of the Caddy config. I considered updating the Caddy config, but in the end it felt too daunting and vulnerable to more configuration drift as the official Nginx configuration will undoubtedly change in the future.

That's why I tried to do only minimal changes to the official advanced nginx config. For this project's nginx config I've turned off SSL and activated linux socket listening. In this way nginx doesn't cause any port collisions and we make Caddy responsible for SSL. And we get to benefit from the security hardening included in the official nginx config.

Maintainability is also improved because we can more easily update our nginx config when there's new updates to the official nginx config.

Support

"If you are using CryptPad in production and require professional support please contact sales@cryptpad.fr" - The CryptPad team

There's also Open Collective where you can support the CryptPad project.

In need of Ansible training or web development services?

There's a very popular book Ansible for Devops by Jeff Gerling, which I gladly recommend.

I also offer freelance services on web development and infrastructure, and hands-on workshops using technologies such as Ansible.

License

AGPLv3