personal_infra/02_vps_core_services_setup.md

02 VPS Core Services Setup

Now that Vipy is ready, we need to deploy some basic services which are foundational for the apps we're actually interested in.

This assumes you've completed the markdown 01.

General tools

This repo contains some rather general tools that you may or may not need depending on what services you want to deploy and what device you're working on. This tools can be installed with the 900 group of playbooks sitting at ansible/infra.

By default, these playbooks are configured for hosts: all. Be mindful if you want to limit, you can use the --limit groupname flag when running the playbook.

Below you have notes on adding each specific tool to a device.

rsync

Simply run the playbook:

ansible-playbook -i inventory.ini infra/900_install_rsync.yml

docker and compose

Simply run the playbook:

ansible-playbook -i inventory.ini infra/910_docker_playbook.yml

Deploy Caddy

• Use Ansible to run the caddy playbook:

  cd ansible
  ansible-playbook -i inventory.ini services/caddy_playbook.yml
  

• Starting config will be empty. Modifying the caddy config file to add endpoints as we add services is covered by the instructions of each service.

Uptime Kuma

Uptime Kuma gets used to monitor the availability of services, keep track of their uptime and notify issues.

Deploy

• Decide what subdomain you want to serve Uptime Kuma on and add it to services/uptime_kuma/uptime_kuma_vars.yml on the uptime_kuma_subdomain.
  • Note that you will have to add a DNS entry to point to the VPS public IP.
• Make sure docker is available on the host.
• Run the deployment playbook: ansible-playbook -i inventory.ini services/uptime_kuma/deploy_uptime_kuma_playbook.yml.

Set up backups to Lapy

• Make sure rsync is available on the host and on Lapy.
• Run the backup playbook: ansible-playbook -i inventory.ini services/uptime_kuma/setup_backup_uptime_kuma_to_lapy.yml.
• A first backup process gets executed and then a cronjob is set up to refresh backups periodically.

Configure

• Uptime Kuma will be available for you to create a user on first start. Do that and store the creds safe.
• From that point on, you can configure through the Web UI.

Restoring to a previous state

• Stop Uptime Kuma.
• Overwrite the data folder with one of the backups.
• Start it up again.

Vaultwarden

Vaultwarden is a credentials manager.

Deploy

• Decide what subdomain you want to serve Vaultwarden on and add it to services/vaultwarden/vaultwarden_vars.yml on the vaultwarden_subdomain.
  • Note that you will have to add a DNS entry to point to the VPS public IP.
• Make sure docker is available on the host.
• Run the deployment playbook: ansible-playbook -i inventory.ini services/vaultwarden/deploy_vaultwarden_playbook.yml.

Configure

• Vaultwarden will be available for you to create a user on first start. Do that and store the creds safely.
• From that point on, you can configure through the Web UI.

Disable registration

• You probably don't want anyone to just be able to register without permission.
• To prevent that, you can run the playbook disable_vaultwarden_sign_ups_playbook.yml after creating the first user.

Set up backups to Lapy

• Make sure rsync is available on the host and on Lapy.
• Run the backup playbook: ansible-playbook -i inventory.ini services/vaultwarden/setup_backup_vaultwarden_to_lapy.yml.
• A first backup process gets executed and then a cronjob is set up to refresh backups periodically.

Restoring to a previous state

• Stop Vaultwarden.
• Overwrite the data folder with one of the backups.
• Start it up again.

Forgejo

Forgejo is a git server.

Deploy

• Decide what subdomain you want to serve Forgejo on and add it to services/forgejo/forgejo_vars.yml on the forgejo_subdomain.
  • Note that you will have to add a DNS entry to point to the VPS public IP.
• Run the deployment playbook: ansible-playbook -i inventory.ini services/forgejo/deploy_forgejo_playbook.yml.

Configure

• Forgejo will be available for you to create a user on first start. Do that and store the creds safely.
• Default behaviour after that is not allow for registrations.
• You can tweak more settings from that point on.
• SSH cloning should work out of the box (after you've set up your SSH pub key in Forgejo, that is).

ntfy

ntfy is a notifications server.

Deploy

• Decide what subdomain you want to serve ntfy on and add it to services/ntfy/ntfy_vars.yml on the ntfy_subdomain.
  • Note that you will have to add a DNS entry to point to the VPS public IP.
• Before running the playbook, you should decide on a user and password for the admin user. This user is the only one authorised to send and read messages from topics. Once you've picked, export them in your terminal like this export NTFY_USER=admin; export NTFY_PASSWORD=secret.
• In the same shell, run the deployment playbook: ansible-playbook -i inventory.ini services/ntfy/deploy_ntfy_playbook.yml.

Configure

• You can visit the ntfy web UI at the FQDN you configured.
• You can start using notify to send alerts with uptime kuma by visiting the uptime kuma UI and using the credentials for the ntfy admin user.
• To receive alerts on your phone, install the official ntfy app: https://github.com/binwiederhier/ntfy-android.
• You can also subscribe on the web UI on your laptop.

Backups

Given that ntfy is almost stateless, no backups are made. If it blows up, simply set it up again.

LNBits

LNBits is a Lightning Network wallet and accounts system.

Deploy

• Decide what subdomain you want to serve LNBits on and add it to services/lnbits/lnbits_vars.yml on the lnbits_subdomain.
  • Note that you will have to add a DNS entry to point to the VPS public IP.
• Run the deployment playbook: ansible-playbook -i inventory.ini services/lnbits/deploy_lnbits_playbook.yml.

Configure

• LNBits will be available for you to create a superuser on first start. Do that and store the creds safely.
• From that point on, you can configure through the Web UI.
• Some advice around specifics of LNbits:
  • The default setup uses a FakeWallet backend for testing. Configure a real Lightning backend as needed by modifying the .env file located or using the superuser UI.
  • For security, disable the new users registration.

Set up backups to Lapy

• Make sure rsync is available on the host and on Lapy.
• Run the backup playbook: ansible-playbook -i inventory.ini services/lnbits/setup_backup_lnbits_to_lapy.yml.
• A first backup process gets executed and then a cronjob is set up to refresh backups periodically. The script backs up both the .env file and the sqlite database. Backups are gpg encrypted for safety.

Restoring to a previous state

• Stop LNBits.
• Overwrite the data folder with one of the backups.
• Start it up again.

ntfy-emergency-app

ntfy-emergency-app is a simple web application that allows trusted people to send emergency messages via ntfy notifications. Perfect for situations where you need to be alerted immediately but don't want to enable notifications on your regular messaging apps.

Deploy

• Decide what subdomain you want to serve the emergency app on and add it to services/ntfy-emergency-app/ntfy_emergency_app_vars.yml on the ntfy_emergency_app_subdomain.
  • Note that you will have to add a DNS entry to point to the VPS public IP.
• Configure the ntfy settings in ntfy_emergency_app_vars.yml:
  • ntfy_emergency_app_topic: The ntfy topic to send messages to (default: "emergency")
  • ntfy_emergency_app_ntfy_url: Your ntfy server URL (default: "https://ntfy.sh")
  • ntfy_emergency_app_ntfy_user: Username for ntfy authentication (optional)
  • ntfy_emergency_app_ntfy_password: Password for ntfy authentication (optional)
  • ntfy_emergency_app_ui_message: Custom message displayed in the web interface
• Make sure docker is available on the host.
• Run the deployment playbook: ansible-playbook -i inventory.ini services/ntfy-emergency-app/deploy_ntfy_emergency_app_playbook.yml.

Personal Blog

Personal blog is a static website served directly by Caddy.

Deploy

• Decide what subdomain you want to serve the blog on and add it to services/personal-blog/personal_blog_vars.yml on the personal_blog_subdomain.
  • Note that you will have to add a DNS entry to point to the VPS public IP.
• Configure the git repository settings in personal_blog_vars.yml:
  • personal_blog_git_repo: The HTTPS URL to your git repository (default: "https://forgejo.contrapeso.xyz/counterweight/pablohere.git")
  • personal_blog_source_folder: The folder within the repo containing static files (default: "public")
• Set up a Forgejo deploy token:
  • Go to your repository → Settings → Deploy Tokens
  • Create a new token with "Read" permissions
  • Copy the token (you won't see it again)
• Export the token as an environment variable: export PERSONAL_BLOG_DEPLOY_TOKEN=your_token_here
• Run the deployment playbook: ansible-playbook -i inventory.ini services/personal-blog/deploy_personal_blog_playbook.yml.

Configure

• The blog will be automatically updated every hour via a cron job that pulls the latest changes from the git repository.
• Static files are served directly by Caddy from the configured webroot directory.
• No additional configuration is needed - the site will be available at your configured domain.

Updating content

• Simply push changes to the master branch of your git repository.
• The cron job will automatically pull and deploy updates within an hour.
• For immediate updates, you can manually run: /usr/local/bin/update-personal-blog.sh on the server.