Controlling uWSGI instances using systemd
=========================================

(aka one service per app)

Modern approach is to let systemd handle starting individual apps while taking
advantage of systemd template unit files and socket activation. Each app will
run under its own user.

Adding a new app to your system is a matter of enabling the socket and
the service. For instance, if one were to configure cgit:

    # systemctl enable uwsgi-app@cgit.socket
    # systemctl start uwsgi-app@cgit.socket

Then configure the ini file `/etc/uwsgi/apps-available/cgit.ini`:

    [uwsgi]
    master = True
    cheap = True
    idle = 600
    die-on-idle = True # If app is not used often, it will exit and be launched
                       # again by systemd as requested by users.

    manage-script-name = True

    plugins = 0:cgi
    cgi = /usr/lib/cgit/cgit.cgi

This will configure a socket activated uwsgi app running as www-cgit (dynamic)
user and made available to the frontend HTTP server via the uWSGI protocol
at the UNIX socket located at /var/uwsgi/cgit.socket .

And last, if applicable, configure your HTTP server the usual way.

The provided template unit uses user `User=www-<confname>` with
`DynamicUser=yes` which locks down many things the uwsgi app instance can do.
Here are some adjustments you might require. They can be implemented using
a systemd unit override (e.g. systemctl edit uwsgi-app@<confname>.service):

    - Change the StateDirectory (instead of the default
      `/var/lib/uwsgi/<confname>`):

        [Service]
        # by default in /var/lib
        Statedirectory=radicale

    - There might be a need to restore old behaviour and use a www-data user
      (instead of the default `www-<confname>`):

        [Service]
        User=www-data
        DynamicUser=no

    - Some services might need write access outside of their StateDirectory.
      For this you can create a standard unix user with persistent uid,
      set up permissions as you wish and use an override in the likes of,
      in the case of a nextcloud instance,
      `/etc/systemd/system/uwsgi-app\@nextcloud.service.d/override.conf`:

        [Service]
        ReadWritePaths=/srv/nextcloud/data

    - There might be a need to use a specific user (instead of the default
      `www-<confname>`):

        [Service]
        User=radicale

    - You may not want to use socket activation and start uwsgi app with
      system startup:

        [Install]
        WantedBy=multi-user.target

    - Anything needing permissions with the daemon user requires to create that
      unix user, DynamicUser=yes will cope with this with no override.


Migrating legacy initscript instances to using systemd template units
=====================================================================

If you want to migrate from the legacy initscript provided by the uwsgi
binary package, the following manual steps are required:

    1. Enable and start socket unit, apply required adjustments, as described
       in the previous section.
    2. Change your HTTP server to point to /run/uwsgi/<confname>.socket
       (instead of /var/run/uwsgi/app/<confname>/socket)
    3. (optional) Add the following lines to
       /etc/uwsgi/apps-available/<confname>.ini to stop the instance if
       not used:
            idle = 600
            die-on-idle = True
    4. (optional) apt purge uwsgi (not used anymore)

Please note that:

    - /etc/uwsgi/apps-enabled is not used anymore.
    - /usr/share/uwsgi/conf/default.ini settings are not used anymore,
      you might want to adjust your app configuration.

Note to Debian package maintainers depending on uwsgi regarding systemd
=======================================================================

The following changes may be required for your package to migrate to using
systemd for starting up your <app>:

    - Adjust your documentation using the above information
    - Consider providing <app>-uwsgi.service to make the life of your users
      easy (e.g. no systemd unit manual overrides)