HotPocket by BTHLabs

Minimal self-hosted bookmarking app :).

The what, the why and the ugly

HotPocket is a minimal self-hosted bookmarking app. It combines a Web application, companion apps, browser extensions to give you a way to quickly save links for later.

HotPocket came to be to fill in the blank left by Pocket, after Mozilla shut it down. I looked at the existing alternatives and found them either too feature-rich, too involved to self-host or otherwise not to my liking. So I decided to sit down and build something for myself.

With the what and why out of the way, let's talk about the ugly... At its core HotPocket is a personal project. I built it by myself and for myself. It may or may not fit your needs. If it does, happy saving!

If you're feeling up for an adventure, continue reading below :).

Development setup

Requirements:

• Python 3.13,
• Poetry 2.2.1,
• git-crypt,
• Docker with Docker Compose and Buildx.

Setup

1. $ git-crypt unlock KEYFILE
2. $ poetry install
3. $ docker buildx bake
4. $ poetry run inv setup

Running local development stack

1. $ docker compose up

Exported services:

• The app: https://app.hotpocket.work.bthlabs.net:8000/
• The admin: https://admin.hotpocket.work.bthlabs.net:8000/
• Keycloak: https://auth.hotpocket.work.bthlabs.net:8443/
• Postgres: postgres://postgres.hotpocket.work.bthlabs.net:5432/
• RabbitMQ: amqp://rabbitmq.hotpocket.work.bthlabs.net:5672/
• RabbitMQ Management: amqp://rabbitmq.hotpocket.work.bthlabs.net:15672/

Default credentials:

The default credentials across most of the services are: hotpocket:hotpocketm4st3r. This applies to the initial app and admin account, Keycloak master realm, Postgres and RabbitMQ.

The Keycloak hotpocket-development realm user's credentials are: hotpocket@bthlabs.net:hotpocketm4st3r. You can use these to log in to the app and admin using OIDC.

Deployment

There are two deployment images - aio and deployment.

The AIO image

The aio image is pre-configured for running small instances in a single container:

• It defaults to SQLite database.
• It defaults to running all background tasks in the foreground.
• It defaults to accepting traffic with any Host HTTP header.

The aio image is recommended for self-hosting with minimal use, e.g. by a single user.

Example:

$ docker run --rm -it \
    -v `realpath run/`:/srv/run \
    -e HOTPOCKET_BACKEND_SECRET_KEY=thisisntright \
    -e HOTPOCKET_BACKEND_INITIAL_ACCOUNT_USERNAME=hotpocket \
    -e HOTPOCKET_BACKEND_INITIAL_ACCOUNT_PASSWORD=hotpocketm4st3r \
    -p 8000:8000 \
    hotpocket/backend:aio-v25.11.19-01

The command above will set up and start the application. The SQLite file will be placed in run/hotpocket-backend-aio.sqlite and database migrations will be ran. The initial superuser account will be created with the specified credentials. The Web app will be reachable at http://127.0.0.1:8000/. The admin will be reachable at http://127.0.0.1:8000/admin/.

The DJANGO_SETTINGS_MODULE environment variable defaults to hotpocket_backend.settings.deployment.aio.

NOTE: The command above specifies wildly insecure SECRET_KEY which is used among other things to secure the session cookie. Please please please don't run it like this. Not even in your homelab :).

The deployment/aio/docker-compose.yaml file can be used as a starting point for AIO deployments.

The Deployment image

The deployment image doesn't make any assumptions about the env and in turn will require the operator to configure database, Celery broker and result backend etc. The final deployment will require services for at least the Web app, the Celery worker and Celery Beat. Admin is optional.

The DJANGO_SETTINGS_MODULE environment variable defaults to hotpocket_backend.settings.deployment.webapp. This should be set to hotpocket_backend.settings.deployment.admin in the Admin container.

The deployment/fullstack/docker-compose.yaml file can be used as a starting point for full-stack deployments.

Configuration environment variables

HotPocket deployment images provide extensive set of environment variables that can be used to configure the services.

Variable	Default	Description
HOTPOCKET_BACKEND_ENV	deployment or aio	The environment name. See below.
HOTPOCKET_BACKEND_APP	webapp	The app name. See below.
HOTPOCKET_BACKEND_DEBUG	false	Django DEBUG setting. Do not enable in production. Only effective in the AIO image.
HOTPOCKET_BACKEND_ALLOWED_HOSTS	N/A or *	Django ALLOWED_HOSTS setting. Required in the Deployment image.
HOTPOCKET_BACKEND_SECRET_KEY	N/A	Django SECRET_KEY setting. Recommended different for the Web app and Admin. Required.
HOTPOCKET_BACKEND_DATABASE_ENGINE	django.db.backends.postgresql or django.db.backends.sqlite3	The database configuration engine.
HOTPOCKET_BACKEND_DATABASE_NAME	N/A or /srv/run/hotpocket-backend-aio.sqlite	The database name.
HOTPOCKET_BACKEND_DATABASE_USER	N/A or N/A	The database user.
HOTPOCKET_BACKEND_DATABASE_PASSWORD	N/A	The database password.
HOTPOCKET_BACKEND_DATABASE_HOST	N/A	The database host.
HOTPOCKET_BACKEND_DATABASE_PORT	5432 or N/A	The database port.
HOTPOCKET_BACKEND_MODEL_AUTH_IS_DISABLED	false	Set to true to disable username and password login.
HOTPOCKET_BACKEND_OIDC_PAYLOAD	N/A	The OIDC configuration payload.
HOTPOCKET_BACKEND_CELERY_BROKER_URL	N/A	The Celery broker URL.
HOTPOCKET_BACKEND_CELERY_RESULT_BACKEND	N/A	The Celery result backend URL.
HOTPOCKET_BACKEND_CELERY_IGNORE_RESULT	false	Set to true to prevent Celery from saving task results.
HOTPOCKET_BACKEND_CELERY_ALWAYS_EAGER	false	Set to true to run Celery tasks in the foreground.
HOTPOCKET_BACKEND_UPLOADS_PATH	/srv/uploads or /srv/run/uploads	The absolute path to user-uploaded files.
HOTPOCKET_BACKEND_GUNICORN_WORKERS	4 or 2	The number of Gunicorn workers to run for Web servers.
HOTPOCKET_BACKEND_RUN_MIGRATIONS	false or true	Set to true to run database muigrations when the container starts.
HOTPOCKET_BACKEND_INITIAL_ACCOUNT_USERNAME	N/A	Username for the initial account.
HOTPOCKET_BACKEND_INITIAL_ACCOUNT_PASSWORD	N/A	Password for the initial account.
HOTPOCKET_BACKEND_OPERATOR_EMAIL	N/A	Instance operator's e-mail. Used to display extra language on login page.

Env and App settings

The HOTPOCKET_BACKEND_ENV and HOTPOCKET_BACKEND_APP variables are used internally to resolve other settings and identify the running app. HOTPOCKET_BACKEND_ENV should only be changed if when creating heavily customized version of the project. HOTPOCKET_BACKEND_APP should generally be set to admin only in the Admin container.

OIDC login configuration

The HOTPOCKET_BACKEND_OIDC_PAYLOAD can be used to enable OIDC login. It must be a JSON string that deserializes to the following object:

{
  "endpoint": "https://some.oidc.host/some-realm/",
  "key": "client-key",
  "secret": "client-secret",
  "scope": ["roles"],
  "display_name": "My OIDC server"
}

The scope field specified additional scopes to request from IdP. It can be ommited and defaults to ["roles"]. The display_name field specifies the method's name in the UI and defaults to OIDC.

NOTE: Currently, only Keycloak has been tested with this login method.

Volumes

Both images declare /srv/run to be a volume. It's intended to keep the service's runtime data, including but not limited to PID files, UNIX sockets etc. It's recommended to persist this volume.

Additionally, the deployment image declares /srv/uploads to be a volume. It's recommeded to persist this volume.

Author

HotPocket is developed by BTHLabs.

License

HotPocket is licensed under the Apache 2.0 License.