hotpocket/README.md

# 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`
1. `$ poetry install`
1. `$ docker buildx bake`
1. `$ 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.26-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](https://www.bthlabs.pl/).

## License

_HotPocket_ is licensed under the Apache 2.0 License.