Editing One Quick Way To Host A WebApp (section)

== The App ==

=== The App Itself ===

The first thing I try to do is get the app running one way or the other. This part is easy and I just iterate locally on my dev machine (a Macbook). Once I've got it running, I try to encode that state into a Docker container. I use [https://orbstack.dev/ Orbstack] to develop on MacOS because it's far more convenient than Docker proper.

This is not-technically required, but since I have low usage, I can pack more things onto a single box with Docker since I don't have to worry about environments clobbering each other. It's also not usually too hard.

=== Database ===

If you're writing a personal application, SQLite is the best tool to reach for. It's a single file and it's easy to deal with. If you're also hosting other things, like I am with Mediawiki, it is worth running your distribution's default MySQL/PostgreSQL on the host itself. If you're going to use Docker later, remember that users will need to be granted permissions to log in from the Docker/Podman network too (which is often 10.x.x.x).

=== Hosting Your Code ===

You can build your app and only deploy the artifacts, but I've found it much easier to just push the source code and build the app on the production host. The way I do this is perhaps unorthodox or perhaps standard.

First, create your app directory:

    mkdir ~/sub.roshangeorge.dev

Then make it into a git repo:

    cd ~/sub.roshangeorge.dev
    git init .

Then on your dev machine, add it as a remote:

    git remote add deploy user@host:~/sub.roshangeorge.dev
    git push deploy main

Now, this would seem to be enough, but you can't push to a branch that is checked out. So what I do is that I only ever have 'releases' checked out. And a release is just a tag. So on my local machine, I might do.

    git tag release-20250313
    git push deploy --tags

And then on the host I check out the relevant tag when I want to run that:

    git checkout release-20250313

This little trick lets me just `git push` when I want to deploy. If you like, you can put in post-commit hooks and all that, but I haven't found them useful. I just ssh on and build.

=== Building ===

I like to have, in each of my repos, a `bin/build` script. For the ones with Dockerfiles these look as simple as:

    #!/usr/bin/env bash
    podman build -t sub.roshangeorge.dev:latest .

A convenience thing I have throughout is that I refer to the app everywhere by some canonical subdomain. The docker tag is the subdomain, the nginx site is the subdomain name, the code directory is the subdomain. Everything is the subdomain.

I also have a `bin/backup` that describes how to backup.

=== Docker ===

I prefer using docker (well podman) for everything because it pins my environment but also because it retains app environments in their own worlds. Mediawiki, which this site is based on, is written in PHP and composer (a PHP package manager) just goes everywhere. With docker, all that is contained in one place.

Other languages don't do this as much. For example, Rust's `cargo` is quite well-contained in that it runs inside a user-context. So I build Rust programs in their own directory. I used to run Python programs in Docker exclusively but with `mise` and `uv` it is possible to run them raw. I still prefer to run them in Docker, though. I just have to remember to make them listen on a unique port, and to expose the port in docker.

=== Systemd ===

With docker/podman, you can just set them to restart or whatever whenever you like and things will stay perpetually running, but I like a single system for all my apps, whether docker or not, and so I use systemd to manage them. An example systemd file looks like this for a docker app:

<syntaxhighlight lang="ini">
[Unit]
Description=App Container
After=network.target

[Service]
Type=simple
User=ubuntu
ExecStart=/usr/bin/podman run --name sub_roshangeorge_dev --mount type=bind,source=/mnt/r2/files,target=/var/www/files -e ENV="var" -p 127.0.0.1:8080:80 sub.roshangeorge.dev:latest
ExecStop=/usr/bin/podman stop sub_roshangeorge_dev
ExecStopPost=/usr/bin/podman rm sub_roshangeorge_dev
Restart=always

[Install]
WantedBy=multi-user.target
</syntaxhighlight>

But you could just as well have a simple non-docker version (this one is a mail server not a web-app but the idea applies)

<syntaxhighlight lang="ini">
[Unit]
Description=Superheap RSS Service
After=network.target

[Service]
Type=simple
User=ubuntu
ExecStart=/home/ubuntu/superheap/target/release/superheap serve -c /home/ubuntu/rss/superheap.json
Restart=always
RestartSec=5
WorkingDirectory=/home/ubuntu

[Install]
WantedBy=multi-user.target
</syntaxhighlight>

While you'll want to symlink these into either `/etc/systemd/system/sub.roshangeorge.dev.service` or `~/.config/systemd/user/sub.roshangeorge.dev.service` if you want to keep them entirely home directory constrained, you can just leave the service unit file in your repo and have it symlinked in. Because your entire repo is on the host, you can just embed all of the host configs in your repo and then appropriately symlink them.