Get started
-----------

After installation, a mirrorbits systemd service is installed, however it's
stopped and disabled, as there's no configuration for mirrorbits yet.

Here's a very quick start:

    # Copy the sample config
    cp /usr/share/doc/mirrorbits/examples/mirrorbits.conf /etc/mirrorbits/

    # Edit it
    $EDITOR /etc/mirrorbits/mirrorbits.conf

    # Start the service
    systemctl start mirrorbits.service

    # When all is good, don't forget to enable it
    systemctl enable mirrorbits.service


HTML templates & third-party assets
-----------------------------------

Mirrorbits provides statistics if the query `?mirrorlist` or `?mirrorstats` is
appended at the end of the URL requested. By default, it returns an HTML page
that fetches assets (javascript and fonts) from third-parties.

Mirrorbits allows the system administrator to change this behavior though, and
serve local assets instead. Here's how to.

First, let's run the helper script that downloads all the assets needed. We
assume that we'll save those in `/srv/SITE/js`.

    mkdir /srv/SITE/js
    /usr/share/mirrorbits/contrib/localjs/fetchfiles.sh /srv/SITE/js

Then configure Mirrorbits to use it. Edit the file `/etc/mirrorbits.conf` and
set `LocalJSPath: /srv/SITE/js`.

Finally you will need to configure your web server to make sure it can serve
the files located in `/srv/SITE/js`.


Debugging
---------

To run mirrorbits in debug mode, you can create a drop-in file to set
DAEMON_ARGS:

    cat << EOF > /etc/systemd/system/mirrorbits.service.d/debug.conf
    [Service]
    Environment=DAEMON_ARGS=-debug
    EOF


Some notes regarding the systemd service
----------------------------------------

`Requires=redis-server.service` is not a good idea. It means that if ever redis
goes down, mirrorbits goes down as well. However mirrorbits is meant to keep
operating even if the database is down, in that case it redirects requests to
the fallback mirrors.

`After=redis-server.service` is not set, meaning that on startup, mirrorbits
doesn't wait for redis to be up, instead it stars asap and redirects requests
to the fallback mirror until redis is up.  If ever you don't like this
behavior, you can create a systemd override file and set
`After=redis-server.service`, or `After=redis-server@%i.service` for the
parameterized service. Replace `redis` with `valkey` if you use valkey.

By default mirrorbits writes its logs to stderr, so the most straightforward
would be use systemd Standard{Output,Error}= directives and let systemd send
the output to a log file. However there's a bit of a chicken-and-egg problem
regarding the creation of the logs directory, as reported at
https://github.com/systemd/systemd/issues/27591. So instead we use mirrorbits
`-log` argument.

`SystemCallFilter=~@resources` doesn't work, the program can't even start.
This is due to Golang, since version 1.19 it calls setrlimit(2) at startup, cf.
https://github.com/golang/go/commit/8427429c.
