dotzenith/tilde

━━━━━━ ❖ ━━━━━━

❖ Information

tilde is an effort to automagically deploy a homeserver with a few useful services using pyinfra. While it's built for personal use cases in mind, it's general enough to be used by anyone. Expect breaking changes, this is forever a work in progress :)

❖ Features

A Wireguard tunnel with a user-friendly interface so you can access your services even when you're not home, without exposing them to the internet.
Dynamic DNS using Cloudflare so that the Wireguard doesn't just stop working randomly.
A Portainer instance to provide a nice GUI to manage all of your docker containers and deploy new ones.
A Nextcloud instance set up with PostgreSQL and Alpine for your own personal cloud storage.
A Jellyfin instance for media consumption.
A Nginx Proxy Manager Instance for reverse proxy and TLS (Configured by the user)

❖ Requirements

While tilde is meant to be very hands off, there's still a few things you'll need to do manually. It's not incredibly complicated, but the instructions are written under the assumption that you're at least a little bit familiar with unix commandline.

❖ The server itself

A machine running Debian 11 or above (for future).
SSH access with a non-root user.
Sudo privileges for the non-root user.

If you don't have ssh keys set up, please take a look at the Github Docs on the topic.

Your ssh config should should look something like this if you're on MacOS:

# .ssh/config

host <homeserver>
  HostName <internal-ip-of-server> 
  user <non-root-user>

host *
  AddKeysToAgent yes
  UseKeychain yes
  IdentityFile ~/.ssh/id_ed25519

Replace <homeserver>, <internal-ip-of-server>, and <non-root-user> with the appropriate values (without the < >)

NOTE: This is for your personal machine, NOT for the server.

If you're on a different OS, the Github guide has instructions for windows and linux as well, I trust that you'll be able to follow them :)

❖ Port forwarding

In order for the Wireguard tunnel to work, you'll need to set up port forwarding on your home router. The instructions can vary from router to router so there are no specific instructions on how to do so.

Once you've figured out how to do so, forward port 51820 to port 51820 of your homeserver.

❖ Dynamic DNS

With a residential internet connection, your public IP is liable to change at any given moment. This is why you'll need to set up Dynamic DNS to make sure the Wireguard tunnel can still connect you to your home network even if your public IP changes.

tilde assumes this will be done using Cloudflare and your own domain. You can also use something like freedns but you'll need to modify some code to get that to work.

Once you have a domain from either Cloudflare itself or transferred over to Cloudflare's DNS servers, you'll need to add a new "A" record. Make sure Proxy status is set to to DNS only.

When you have all of that taken care of, you'll just need to fill out the update script

NOTE: You only need to fill out the following values, the script also has instructions on how to get these values:

auth_email
auth_key
zone_identifier
record_name
sitename (optional)

❖ Environment Variables

As the final step of preparation, you'll need to fill out some environment variables in the run script and the .env file for the docker-compose files.

# run.sh

export SERVER_USER=<non-root-user>
export HOMESERVER=<homeserver-from-your-ssh-config>

# .env

POSTGRES_PASSWORD=<password-you-want-for-nextcloud-db>
WG_PASS=<password-you-want-for-wireguard-ui>
WG_HOST=<record_name.your_domain.com>

Without the < >

❖ Deploying.

Phew that was a lot!! But we're finally ready to deploy!

tilde only has two main dependencies pyinfra and python-dotenv. You can either use Poetry like I do, or just use a venv and install the packages yourself, it's totally up to you!

❖ Using Poetry

$ poetry shell    # Open up a virtual env using Poetry
$ poetry install  # Install pyinfra and dotenv 
$ ./run.sh        # Run tilde on your homeserver

❖ Using a normal venv

$ python3 -m venv tilde_venv          # Create a venv for tilde
$ source tilde_venv/bin/activate      # Activate the venv
$ pip3 install pyinfra python-dotenv  # Install pyinfra and dotenv
$ ./run.sh                            # Run tilde on your homeserver

If everything goes as expected, you'll have a shiny new homeserver complete with all the features mentioned earlier!

The services are available at homeserver-internal-ip:service-port

The mapping for the ports is as follows:

wireguard: 51821
portainer: 9000
nextcloud: 8080
jellyfin: 8096

Feel free to use Nginx Proxy Manager to set up internal domains for these services

❖ What's New?

0.4.1 - Dependency update

dotzenith / tilde