microblog/docs/install.md

Installing

[TOC]

Docker edition

Assuming Docker and Docker Compose are already installed.

For now, there's no image published on Docker Hub, this means you will have to build the image locally.

Clone the repository, replace you-domain.tld by your own domain.

Note that if you want to serve static assets via your reverse proxy (like nginx), clone it in a place where it is accessible by your reverse proxy user.

git clone https://git.sr.ht/~tsileo/microblog.pub your-domain.tld

Build the Docker image locally.

make build

Run the configuration wizard.

make config

Update data/profile.toml and add this line in order to process headers from the reverse proxy:

trusted_hosts = ["*"]

Start the app with Docker Compose, it will listen on port 8000 by default. The port can be tweaked in the docker-compose.yml file.

docker compose up -d

Setup a reverse proxy (see the Reverse Proxy section).

Updating

To update microblogpub, pull the latest changes, rebuild the Docker image and restart the process with docker compose.

git pull
make build
docker compose stop
docker compose up -d

As you probably already know, Docker can (and will) eat a lot of disk space, when updating you should prune old images from time to time:

docker image prune -a --filter "until=24h"

Python developer edition

Assuming you have a working Python 3.10+ environment.

Setup Poetry.

curl -sSL https://install.python-poetry.org | python3 -

Clone the repository.

git clone https://git.sr.ht/~tsileo/microblog.pub testing.microblog.pub

Install deps.

poetry install

Setup config.

poetry run inv configuration-wizard

Setup the database.

poetry run inv migrate-db

Grab your virtualenv path.

poetry env info

Run the two processes with supervisord.

VENV_DIR=/home/ubuntu/.cache/pypoetry/virtualenvs/microblogpub-chx-y1oE-py3.10 poetry run supervisord -c misc/supervisord.conf -n

Setup a reverse proxy (see the next section).

Updating

To update microblogpub locally, pull the remote changes and run the update task to regenerate the CSS and run any DB migrations.

git pull
poetry run inv update

Reverse proxy

You will also want to setup a reverse proxy like NGINX, see uvicorn documentation:

If you don't have a reverse proxy setup yet, NGINX + certbot is recommended.

server {
    client_max_body_size 4G;

    location / {
      proxy_set_header Host $http_host;
      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
      proxy_set_header X-Forwarded-Proto $scheme;
      proxy_set_header Upgrade $http_upgrade;
      proxy_set_header Connection $connection_upgrade;
      proxy_redirect off;
      proxy_buffering off;
      proxy_pass http://localhost:8000;
    }

    # [...]
}

# This should be outside the `server` block
map $http_upgrade $connection_upgrade {
  default upgrade;
  '' close;
}

Optionally, you can serve static files using NGINX directly, with an additional location block. This will require the NGINX user to have access to the static/ directory.

server {
    # [...]

    location / {
        # [...]
    }

    location /static {
       # path for static files
       rewrite ^/static/(.*) /$1 break;
       root /path/to/your-domain.tld/app/static/;
       expires 1y;
    }

    # [...]
}

NGINX config tips

Enable HTTP2 (which is disabled by default):

server {
    # [...]
    listen [::]:443 ssl http2;
}

Tweak /etc/nginx/nginx.conf and add gzip compression for ActivityPub responses:

http {
    # [...]
    gzip_types text/plain text/css application/json application/javascript application/activity+json application/octet-stream;
}

(Advanced) Running on a subdomain

It is possible to run microblogpub on a subdomain (sub.domain.tld) while being reachable from the root root domain (domain.tld) using the name@domain.tld handle.

This requires forwarding/proxying requests from the root domain to the subdomain, for example using NGINX:

location /.well-known/webfinger {
  add_header Access-Control-Allow-Origin '*';
  return 301 https://sub.domain.tld$request_uri;
}

And updating data/profile.toml to specify the root domain as the webfinger domain:

webfinger_domain = "domain.tld"

Once configured correctly, people will be able to follow you using name@domain.tld, while using sub.domain.tld for the web interface.

(Advanced) Running from subpath

It is possible to configure microblogpub to run from subpath. To achieve this, do the following configuration between config and start steps. i.e. after you run make config or poetry run inv configuration-wizard, but before you run docker compose up or poetry run supervisord. Changing this settings on an instance which has some posts or was seen by other instances will likely break links to these posts or federation (i.e. links to your instance, posts and profile from other instances).

The following steps will explain how to configure instance to be available at https://example.com/subdir. Change them to your actual domain and subdir.

• Edit data/profile.toml file, add this line:

    id = "https://example.com/subdir"
  

• Edit misc/*-supervisord.conf file which is relevant to you (it depends on how you start microblogpub - if in doubt, do the same change in all of them) - in [program:uvicorn] section, in the line which starts with command, add this argument at the very end: --root-path /subdir

Above two steps are enough to configure microblogpub. Next, you also need to configure reverse proxy. It might slightly differ if you plan to have other services running on the same domain, but for NGINX config shown above, the following changes are enough:

• Add subdir to location, so location block starts like this:

    location /subdir {
  

• Add / at the end of proxy_pass directive, like this:

    proxy_pass http://localhost:8000/;
  

These two changes will instruct NGINX that requests sent to https://example.com/subdir/... should be forwarded to http://localhost:8000/....

• Inside server block, add redirects for well-known URLs (add these lines after client_max_body_size, remember to replace subdir with your actual subdir!):

    location /.well-known/webfinger { return 301 /subdir$request_uri; }
    location /.well-known/nodeinfo  { return 301 /subdir$request_uri; }
    location /.well-known/oauth-authorization-server  { return 301 /subdir$request_uri; }
  

• Optionally, check robots.txt from a running microblogpub instance and integrate it into robots.txt file in the root of your server - remember to prepend subdir to URLs, so for example Disallow: /admin becomes Disallow: /subdir/admin.

YunoHost edition

YunoHost support is available (although it is not an official package for now): https://git.sr.ht/~tsileo/microblog.pub_ynh.

Available tutorial/guides

• Opalstack, thanks to @defulmere@mastodon.social.