You've already forked hotpocket
This commit is contained in:
167
README.md
Normal file
167
README.md
Normal file
@@ -0,0 +1,167 @@
|
||||
# HotPocket by BTHLabs
|
||||
|
||||
This repository contains the _HotPocket_ project.
|
||||
|
||||
## Development setup
|
||||
|
||||
### Requirements:
|
||||
|
||||
* Python 3.12,
|
||||
* Poetry 1.8.3,
|
||||
* `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 \
|
||||
docker-hosted.nexus.bthlabs.pl/hotpocket/backend:aio-v1.0.0-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.webapp`. This should be set to
|
||||
`hotpocket_backend.settings.deployment.admin` in the Admin container.
|
||||
|
||||
**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.aio`.
|
||||
|
||||
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. |
|
||||
|
||||
**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.
|
||||
|
||||
## Author
|
||||
|
||||
_HotPocket_ is developed by [BTHLabs](https://www.bthlabs.pl/).
|
||||
|
||||
## License
|
||||
|
||||
_HotPocket_ is licensed under the Apache 2.0 License.
|
||||
Reference in New Issue
Block a user