misc: upgrade-related migrations and small fixes

CHANGELOG.md

@@ -1,36 +1,6 @@
 # Changelog
 
-You can [view the published changelog here](https://docs.kegbot.org/projects/kegbot-server/en/latest/releases/changelog.html).
+The changelog is maintained at
+[`docs/source/releases/changelog.rst`](docs/source/releases/changelog.rst).
 
-## Current version (unreleased)
-
-A modernization release. The runtime, framework, and toolchain were all brought
-up to date.
-
-### Highlights
-
-- **Python 3.14** is now required (was 3.10).
-- **Django 5.2 LTS** (was 3.2).
-- Web server switched from **gunicorn/gevent** to **waitress**.
-- Packaging moved from **Poetry** to **uv**; linting/formatting moved to **ruff**;
-  pre-flight checks run via **pre-commit**.
-- protobuf upgraded to the 6.x series.
-- Docker image rebuilt on `python:3.14-slim` with uv.
-- **Very old backups can now be restored directly.** `kegbot restore` accepts
-  legacy format-1 backups (created by Kegbot v1.1.x) and upgrades their data in
-  one step; no intermediate 1.2/1.3 install is needed.
-
-### Upgrade notes (for existing installs)
-
-- **Everyone is logged out once.** Sessions now use the JSON serializer (Django
-  removed the pickle serializer), so existing session cookies are invalidated on
-  upgrade. Users simply log in again.
-- **Background jobs enqueue on database commit.** Stats/notification jobs are now
-  handed to the worker only after the surrounding DB transaction commits. Ensure
-  `run_workers` is running (unchanged) to process them.
-- **`run_gunicorn` was removed.** Use `kegbot run_server` (now waitress). Tune
-  with `--waitress_options` (e.g. `--threads=8`); `$PORT` is still honored.
-- The Docker image no longer publishes a `linux/arm/v7` variant (amd64 + arm64
-  only).
-- The legacy gflags-based Python API client was removed from the server package;
-  it lives in the separate kegbot-api project.
+You can also [view it on the web](https://docs.kegbot.org/projects/kegbot-server/en/latest/releases/changelog.html).

docker-compose.yml

@@ -4,8 +4,6 @@
 # make the appropriate changes to `docs/source/docker-compose.example.yml`
 # as well.
 
-version: '3'
-
 services:
   kegbot:
     image: kegbot-server
@@ -24,6 +22,11 @@ services:
       DATABASE_URL: mysql://kegbot_dev:changeme@mysql/kegbot_dev
       KEGBOT_ENV: "debug"
       KEGBOT_SECRET_KEY: "changeme"
+    depends_on:
+      mysql:
+        condition: service_healthy
+      redis:
+        condition: service_started
 
   workers:
     image: kegbot-server
@@ -37,17 +40,29 @@ services:
     environment:
       REDIS_URL: redis://redis:6379/0
       DATABASE_URL: mysql://kegbot_dev:changeme@mysql/kegbot_dev
-      KEGBOT_DEBUG: "true"
+      KEGBOT_ENV: "debug"
       KEGBOT_SECRET_KEY: "changeme"
+    depends_on:
+      mysql:
+        condition: service_healthy
+      redis:
+        condition: service_started
 
   mysql:
-    image: mysql:latest
+    image: mysql:8
     restart: always
     environment:
       MYSQL_ROOT_PASSWORD: 'changeme'
       MYSQL_USER: 'kegbot_dev'
       MYSQL_PASSWORD: 'changeme'
       MYSQL_DATABASE: 'kegbot_dev'
+    healthcheck:
+      # Ping over TCP: during init the image runs a socket-only temporary
+      # server that would pass a plain socket ping too early.
+      test: ["CMD", "mysqladmin", "ping", "-h127.0.0.1", "--silent"]
+      interval: 5s
+      timeout: 5s
+      retries: 30
     tmpfs:
       - /tmp
       - /var/tmp

docs/source/commands.rst

@@ -9,12 +9,12 @@ This section describes commonly-used commands that are available from the
 Running commands
 ----------------
 
-When using ``docker-compose``, you can run the ``kegbot`` command line using
+When using ``docker compose``, you can run the ``kegbot`` command line using
 the following general invocation:
 
 .. code-block:: console
 
-    $ docker-compose run kegbot <command-name> [.. additional args ..]
+    $ docker compose run kegbot <command-name> [.. additional args ..]
 
 For an example, see the :ref:`upgrading` section.
 
@@ -40,11 +40,22 @@ Kegbot Server.
 
   Change the password of the given user.
 
+.. data:: backup
+
+  Creates a zipfile backup of the database and stored media. The backup is
+  written to the ``backups/`` folder of the site's media storage.
+
+.. data:: restore <zipfile>
+
+  Restores a backup zipfile into a fresh (erased) system. Backups created
+  by Kegbot v1.1.x are upgraded automatically during restore; see
+  :ref:`upgrade-legacy`.
+
 
 Internal commands
 ~~~~~~~~~~~~~~~~~
 
-These commands are what makes the Kegbot Server run. When using ``docker-compose``,
+These commands are what makes the Kegbot Server run. When using ``docker compose``,
 you should not need to call these commands directly, as they're invoked by that
 configuration when needed.
 

docs/source/developers.rst

@@ -10,44 +10,59 @@ Local environment
 -----------------
 
 Most likely, you'll want to run kegbot locally (outside of Docker) while
-developing. We use `Poetry` to manage the Python environment. Create
-your development environment this way:
+developing. We use `uv <https://docs.astral.sh/uv/>`_ to manage the Python
+environment. Create your development environment this way:
 
 .. code-block:: console
 
-  $ poetry install
+  $ uv sync --all-groups
 
-This will fetch and install all dependencies, and create a virtual Python
-environment.
+This will fetch and install all dependencies into a virtual Python
+environment at ``.venv``.
 
-Whenever you want to run code or tests, step into a development shell:
+A few settings are required even in development. A minimal configuration,
+using sqlite and a local redis:
 
 .. code-block:: console
 
-  $ poetry shell
-  (kegbot-server) $ ./bin/kegbot version
-  1.3.0
+  $ export KEGBOT_SECRET_KEY=changeme
+  $ export DATABASE_URL=sqlite:///kegbot-dev.db
+  $ export REDIS_URL=redis://localhost:6379/0
+
+Run the server, or any other command, through ``uv run``:
+
+.. code-block:: console
+
+  $ uv run bin/kegbot version
+  $ uv run bin/kegbot migrate
+  $ uv run bin/kegbot run_server
 
 Running tests
 -------------
 
-We use `pytest` to run tests. Run all tests this way:
+We use `pytest` to run tests. The test suite runs against sqlite and needs
+no redis server:
 
 .. code-block:: console
 
-  (kegbot-server) $ pytest
-
+  $ uv run pytest
 
-Code format
------------
+Code format and lint
+--------------------
 
-We use `black` to format all code. Run it this way:
+We use `ruff` to format and lint all code:
 
 .. code-block:: console
 
-  $ poetry shell
-  (kegbot-server) $ black pykeg/
+  $ uv run ruff format
+  $ uv run ruff check
 
+To run these checks automatically before each commit, install the
+`pre-commit` hooks:
+
+.. code-block:: console
+
+  $ uv run pre-commit install
 
 Building docs
 -------------
@@ -56,8 +71,5 @@ We use `Sphinx` to build docs. You can create them this way:
 
 .. code-block:: console
 
-  $ poetry shell
-  (kegbot-server) $ cd docs
-  (kegbot-server) $ make html
-  (kegbot-server) $ open build/html/index.html
-
+  $ uv run sphinx-build -b html docs/source docs/build/html
+  $ open docs/build/html/index.html

docs/source/docker-compose.example.yml

@@ -1,8 +1,6 @@
-version: '3'
-
 services:
   kegbot:
-    image: ghcr.io/kegbot/server:stable
+    image: ghcr.io/kegbot/server:latest
     restart: unless-stopped
     command: run_server
     ports:
@@ -17,9 +15,14 @@ services:
       DATABASE_URL: mysql://kegbot:changeme@mysql/kegbot
       KEGBOT_ENV: "debug"
       KEGBOT_SECRET_KEY: "changeme"
+    depends_on:
+      mysql:
+        condition: service_healthy
+      redis:
+        condition: service_started
 
   workers:
-    image: ghcr.io/kegbot/server:stable
+    image: ghcr.io/kegbot/server:latest
     restart: unless-stopped
     command: run_workers
     volumes:
@@ -32,15 +35,27 @@ services:
       DATABASE_URL: mysql://kegbot:changeme@mysql/kegbot
       KEGBOT_ENV: "debug"
       KEGBOT_SECRET_KEY: "changeme"
+    depends_on:
+      mysql:
+        condition: service_healthy
+      redis:
+        condition: service_started
 
   mysql:
-    image: mysql:latest
+    image: mysql:8
     restart: always
     environment:
       MYSQL_ROOT_PASSWORD: 'changeme'
       MYSQL_USER: 'kegbot'
       MYSQL_PASSWORD: 'changeme'
       MYSQL_DATABASE: 'kegbot'
+    healthcheck:
+      # Ping over TCP: during init the image runs a socket-only temporary
+      # server that would pass a plain socket ping too early.
+      test: ["CMD", "mysqladmin", "ping", "-h127.0.0.1", "--silent"]
+      interval: 5s
+      timeout: 5s
+      retries: 30
     tmpfs:
       - /tmp
       - /var/tmp

docs/source/install.rst

@@ -7,7 +7,7 @@ Prerequisites
 -------------
 
 Kegbot Server is installed and supported through `Docker <https://docs.docker.com/get-docker/>`_
-and `docker-compose <https://docs.docker.com/compose/>`_, which are available for Mac,
+and `Docker Compose <https://docs.docker.com/compose/>`_, which are available for Mac,
 Windows, and Linux.
 
 Ensure you have both of these installed before continuing.
@@ -27,9 +27,9 @@ Create the config file
 ----------------------
 
 Kegbot and its essential services will be configured and launched using the
-``docker-compose`` tool and a corresponding config file, ``docker-compose.yml``.
+``docker compose`` tool and a corresponding config file, ``docker-compose.yml``.
 
-Create a new filed called ``docker-compose.yml`` starting with the following contents:
+Create a new file called ``docker-compose.yml`` starting with the following contents:
 
 .. include:: ./docker-compose.example.yml
    :literal:
@@ -53,10 +53,10 @@ To this::
 Start the services
 ------------------
 
-Now, ask ``docker-compose`` to launch these services. We will launch them in the
+Now, ask ``docker compose`` to launch these services. We will launch them in the
 foreground::
 
-    $ docker-compose up
+    $ docker compose up
 
 This may take a while, as the Docker system works to download the images it needs.
 Eventually, you should start seeing a series of output like the following::
@@ -113,7 +113,7 @@ them in the background:
 
 .. code-block:: console
 
-    $ docker-compose up -d
+    $ docker compose up -d
 
 This time, you should see only a few brief lines of output:
 
@@ -125,13 +125,13 @@ This time, you should see only a few brief lines of output:
     ⠿ Container kegbot-server-redis-1    Started             0.6s
     ⠿ Container kegbot-server-workers-1  Started             0.6s
 
-You can verify everything is running with the ``docker-compose ps`` command:
+You can verify everything is running with the ``docker compose ps`` command:
 
 .. code-block:: console
 
-    $ docker-compose ps
+    $ docker compose ps
     NAME                      COMMAND                  SERVICE     STATUS      PORTS
-    kegbot-server-kegbot-1    "gunicorn pykeg.web.…"   kegbot      running     0.0.0.0:8000->8000/tcp
+    kegbot-server-kegbot-1    "/usr/local/sbin/kegbo…"   kegbot      running     0.0.0.0:8000->8000/tcp
     kegbot-server-mysql-1     "docker-entrypoint.s…"   mysql       running     3306/tcp, 33060/tcp
     kegbot-server-redis-1     "docker-entrypoint.s…"   redis       running     6379/tcp
-    kegbot-server-workers-1   "bin/kegbot run_work…"   workers     running     8000/tcp
+    kegbot-server-workers-1   "/usr/local/sbin/kegbo…"   workers     running     8000/tcp

docs/source/overview.rst

@@ -10,7 +10,7 @@ installing a new Kegbot server.
 Prerequisites
 -------------
 
-Kegbot Server requires `Docker <https://get.docker.sh/>`_ to run, and
+Kegbot Server requires `Docker <https://docs.docker.com/get-docker/>`_ to run, and
 runs on any operating system that supports Docker. We have tested these
 instructions on Linux and Mac OS X machines.
 

docs/source/releases/changelog.rst

@@ -6,6 +6,42 @@ Changelog
 **Upgrade Procedure:** Please follow :ref:`upgrading` for general upgrade steps.
 
 
+Version 2.0.0 (unreleased)
+--------------------------
+
+A modernization release. The runtime, framework, and toolchain were all
+brought up to date.
+
+**Highlights**
+
+* Python 3.14 is now required (was 3.10).
+* Django 5.2 LTS (was 3.2).
+* Web server switched from gunicorn/gevent to waitress.
+* Packaging moved from Poetry to uv; linting and formatting moved to ruff.
+* protobuf upgraded to the 6.x series.
+* Docker image rebuilt on ``python:3.14-slim`` with uv; images are published
+  to ``ghcr.io/kegbot/server``.
+* **Very old backups can now be restored directly.** ``kegbot restore``
+  accepts legacy format-1 backups (created by Kegbot v1.1.x) and upgrades
+  their data in one step; no intermediate 1.2/1.3 install is needed.
+* Time zone choices are now derived from the system time zone database.
+
+**Upgrade notes**
+
+* **Everyone is logged out once.** Sessions now use the JSON serializer, so
+  existing session cookies are invalidated on upgrade. Users simply log in
+  again.
+* **Background jobs enqueue on database commit.** Stats and notification
+  jobs are handed to the worker only after the surrounding database
+  transaction commits. Ensure ``run_workers`` is running (unchanged) to
+  process them.
+* ``run_gunicorn`` was removed. Use ``kegbot run_server`` (now waitress).
+* The Docker image no longer publishes a ``linux/arm/v7`` variant (amd64 and
+  arm64 only).
+* The legacy gflags-based Python API client was removed from the server
+  package; it lives in the separate kegbot-api project.
+
+
 Version 1.3.0 (2022-08-10)
 --------------------------
 

docs/source/settings.rst

@@ -15,7 +15,7 @@ This section lists all settings (environment variables) the server recognizes.
 Required settings
 ~~~~~~~~~~~~~~~~~
 
-These settings have no default and must be set by you. (When you use ``docker-compose``
+These settings have no default and must be set by you. (When you use ``docker compose``
 with the example configuration in these docs, all required values will be set.)
 
 .. data:: DATABASE_URL