feat: Integrate prose-pod-api

.gitignore

@@ -1,8 +1,15 @@
-# Editor
-.nova
-
 # macOS
 .DS_Store
 
 # Env
 .env
+
+# Configuration files (not templates or examples)
+Prose.toml
+
+# Content files
+pod-fs-root/
+*.sqlite
+
+# Editors
+.nova

Prose.toml → Prose-example.toml

@@ -1,7 +1,7 @@
 # Prose Pod API
 # REST API for administrating a Prose Pod
 # Configuration file
-# Example: https://github.com/prose-im/prose-pod-api/blob/master/Prose.toml
+# Example: https://github.com/prose-im/prose-pod-api/blob/master/Prose-example.toml
 # All keys: https://github.com/prose-im/prose-pod-api/blob/master/service/src/config/mod.rs
 
 [branding]

Prose-template.toml

@@ -0,0 +1,21 @@
+# Prose Pod API
+# REST API for administrating a Prose Pod
+# Configuration file
+# Example: https://github.com/prose-im/prose-pod-api/blob/master/Prose-example.toml
+# All keys: https://github.com/prose-im/prose-pod-api/blob/master/service/src/config/mod.rs
+
+[branding]
+page_url = "https://admin.prose.<INSERT_YOUR_DOMAIN>/"
+company_name = "<INSERT_YOUR_COMPANY_NAME>"
+
+[notify]
+
+[notify.email]
+from = "prose@<INSERT_YOUR_SMTP_DOMAIN>"
+to = "prose@<INSERT_YOUR_SMTP_DOMAIN>"
+
+smtp_host = "localhost"
+smtp_port = 587
+smtp_username = "<INSERT_SMTP_USERNAME>"
+smtp_password = "<INSERT_SMTP_PASSWORD>"
+smtp_encrypt = false

README.md

@@ -1,39 +1,22 @@
-# prose-pod-system
+# Prose Pod System
 
 [![Test](https://github.com/prose-im/prose-pod-system/actions/workflows/test.yml/badge.svg?branch=master)](https://github.com/prose-im/prose-pod-system/actions/workflows/test.yml)
 
 **Prose Pod system configurations and build rules. Used to package everything together.**
 
 Copyright 2022, Prose Foundation - Released under the [Mozilla Public License 2.0](./LICENSE.md).
 
-## Launching both the XMPP server and the Admin API
+## :information_source: Usage
 
-To launch both the XMPP server (`prose-pod-server`) and the Admin API (`prose-pod-api`), you can use [Docker Compose](https://docs.docker.com/compose/).
+See [USAGE.md](./USAGE.md).
 
-First, create a `.env` file at the repository root containing required secrets and localhost overrides:
-
-```bash
-export JWT_SIGNING_KEY='<INSERT_JWT_SIGNING_KEY>'
-export PROSE_API__ADMIN_PASSWORD='<INSERT_VERY_STRONG_PASSWORD>'
-export PROSE_SERVER__DOMAIN='prose.org.local'
-export RUST_LOG='info,sqlx=warn'
-```
-
-Then, run `docker compose up` and everything should work.
-
-## Tools
-
-Some tools are available to ease working on Prose:
-
-- **Bootstrap local Prose server** (without the admin API): `./tools/bootstrap.sh [environment]`
-  - `[environment]`: _defaults to `local`_
-
-## License
+## :balance_scale: License
 
 Licensing information can be found in the [LICENSE.md](./LICENSE.md) document.
 
 ## :fire: Report A Vulnerability
 
-If you find a vulnerability in any Prose system, you are more than welcome to report it directly to Prose Security by sending an encrypted email to [[email protected]](mailto:[email protected]). Do not report vulnerabilities in public GitHub issues, as they may be exploited by malicious people to target production systems running an unpatched version.
+If you find a vulnerability in any Prose System, you are more than welcome to report it directly to Prose Security by sending an encrypted email to [[email protected]](mailto:[email protected]). Do not report vulnerabilities in public GitHub issues, as they may be exploited by malicious people to target production systems running an unpatched version.
 
-**:warning: You must encrypt your email using Prose Security GPG public key: [:key:57A5B260.pub.asc](https://files.prose.org/public/keys/gpg/57A5B260.pub.asc).**
+> [!WARNING]
+> **You MUST encrypt your email using Prose Security GPG public key: [:key:57A5B260.pub.asc](https://files.prose.org/public/keys/gpg/57A5B260.pub.asc).**

USAGE.md

@@ -0,0 +1,91 @@
+# Usage guidelines
+
+This repository is meant to be used in various ways. This guide explains how to start a Prose Pod or Prose Pod Server depending on your use case.
+
+## Starting a Prose Pod
+
+To launch both the XMPP server (`prose-pod-server`) and the Admin API (`prose-pod-api`), you can use [Docker Compose](https://docs.docker.com/compose/).
+
+### Use case: Running a Prose Pod locally (with persisting data)
+
+1. ### Configure the Prose Pod
+
+   Some static configuration is required to bootstrap and run a Prose Pod. Here is how you can copy the templates:
+
+   ```bash
+   cd PROSE_POD_SYSTEM_DIR # Replace with your path to `prose-pod-system`
+   cp Prose-template.toml Prose.toml
+   cp template.env .env
+   ```
+
+   Then, edit `Prose.toml` and `.env` to fill it with your own configuration.
+
+2. ### Create the API database
+
+   The Prose Pod API uses a [SQLite] database so you need to create one:
+
+   ```bash
+   touch database.sqlite
+   ```
+
+   Tip: You can change the database location by setting `DATABASE_PATH` before running `docker compose up`.
+
+3. ### Copy the filesystem
+
+   While you *could* start the Prose Pod mounting its filesystem on `./server/pod`, you should copy it to avoid loosing data when running `tools/cleanup`. You can easily do so by running:
+
+   ```bash
+   cp -R ./server/pod ./pod-fs-root
+   ```
+
+4. ### Run the Prose Pod
+
+   Finally, run the Prose Pod using:
+
+   ```bash
+   SERVER_ROOT=./pod-fs-root docker compose up
+   ```
+
+   Tip: If you just want to check that the Prose Pod starts correctly, you can run:
+
+   ```bash
+   PROSE_CONFIG_FILE="$(pwd)/Prose-example.toml" docker compose up
+   ```
+
+### Use case: Running an ephemeral Prose Pod locally (e.g. for quick integration tests)
+
+```bash
+ENV_FILE=PATH_TO_ENV_FILE \
+PROSE_CONFIG_FILE=PATH_TO_PROSE_TOML \
+SERVER_ROOT=PATH_TO_SERVER_FS_ROOT \
+docker compose up
+```
+
+See [`prose-pod-api/scripts/integration-test`] for a real-life example.
+
+### Use case: Running an ephemeral Prose Pod on a Raspberry Pi (e.g. for complete integration tests)
+
+> [!WARNING]
+> This section is pretty advanced and requires a complex setup. It's not intended for everyone, just for the few maintainers who'd like to run the full integration test suite at home.
+
+Since integration tests are located in the [`prose-pod-api`] repository, helper scripts are located under [`prose-pod-api/scripts/prose-pod-on-rpi/`].
+
+```bash
+cd PATH_TO_PROSE_POD_API
+# Initialize the Prose Pod.
+./scripts/prose-pod-on-rpi/init --help
+# Cleanup the Prose Pod between test runs.
+./scripts/prose-pod-on-rpi/cleanup --help
+# Deinitialize (delete) the Prose Pod.
+./scripts/prose-pod-on-rpi/deinit --help
+```
+
+## Starting only a Prose Pod Server
+
+- **Bootstrap local Prose server** (without the admin API): `./tools/bootstrap ENVIRONMENT`
+  - `ENVIRONMENT`: `local` or `pod` (directories under [`server/`](./server)). Defaults to `local`.
+
+[`prose-pod-api/scripts/prose-pod-on-rpi/`]: https://github.com/prose-im/prose-pod-api/tree/master/scripts/prose-pod-on-rpi "prose-pod-api/scripts/prose-pod-on-rpi at master · prose-im/prose-pod-api"
+[`prose-pod-api/scripts/integration-test`]: https://github.com/prose-im/prose-pod-api/blob/78cdb14827999f590a5fcff37ef2bd838b30a1b4/scripts/integration-test "prose-pod-api/scripts/integration-test at 78cdb14827999f590a5fcff37ef2bd838b30a1b4 · prose-im/prose-pod-api"
+[`prose-pod-api`]: https://github.com/prose-im/prose-pod-api "prose-im/prose-pod-api: Prose Pod API server. REST API used for administration and management."
+[SQLite]: https://www.sqlite.org/index.html "SQLite homepage"

compose.yaml

@@ -1,42 +1,42 @@
 services:
   api:
-    image: proseim/prose-pod-api
+    image: proseim/prose-pod-api:latest
     ports:
       - "8000:8000"
       - "8080:8080"
     volumes:
-      - ./database.db:/database.db
-      - "${PROSE_CONFIG_FILE:-./Prose.toml}:/Prose.toml"
-      - ./Rocket.toml:/Rocket.toml
-      - ./server/pod/etc/prosody/:/etc/prosody/
+      - "${DATABASE_PATH-./database.sqlite}:/database.sqlite"
+      - "${PROSE_CONFIG_FILE-./Prose.toml}:/Prose.toml"
+      - "${ROCKET_CONFIG_FILE-./Rocket.toml}:/Rocket.toml"
+      - "${SERVER_ROOT:-}/etc/prosody/:/etc/prosody/"
     networks:
       prose-network:
         aliases:
           - prose-pod-api
     environment:
       - RUST_LOG_STYLE=always
     env_file:
-      - "${ENV_FILE:-.env}"
+      - "${ENV_FILE-.env}"
 
   server:
-    image: proseim/prose-pod-server
+    image: proseim/prose-pod-server:latest
     ports:
       - "5222:5222"
       - "5269:5269"
       - "5280:5280"
       - "5582:5582"
     volumes:
-      - ./server/pod/etc/prosody/:/etc/prosody/
-      - ./server/pod/var/lib/prosody/:/var/lib/prosody/
+      - "${SERVER_ROOT:-}/etc/prosody/:/etc/prosody/"
+      - "${SERVER_ROOT:-}/var/lib/prosody/:/var/lib/prosody/"
     networks:
       prose-network:
         aliases:
           - prose-pod-server
           - prose-pod-server-admin
     env_file:
-      - "${ENV_FILE:-.env}"
+      - "${ENV_FILE-.env}"
     entrypoint: >
-      sh -c "cp etc/prosody/prosody.cfg.lua.initial etc/prosody/prosody.cfg.lua && prosody"
+      sh -c "cp /etc/prosody/prosody.cfg.lua.initial /etc/prosody/prosody.cfg.lua && prosody"
 
 networks:
   prose-network: {}

server/pod/etc/prosody/prosody.cfg.lua.initial

@@ -68,4 +68,4 @@ VirtualHost "admin.prose.org.local"
 
   -- mod_init_admin
   init_admin_jid = "[email protected]"
-  init_admin_password_env_var_name = "PROSE_API__ADMIN_PASSWORD"
+  init_admin_password_env_var_name = "PROSE_BOOTSTRAP__PROSE_POD_API_XMPP_PASSWORD"

template.env

@@ -0,0 +1,5 @@
+#!/bin/bash
+
+export JWT_SIGNING_KEY='<INSERT_JWT_SIGNING_KEY>'
+export PROSE_BOOTSTRAP__PROSE_POD_API_XMPP_PASSWORD='<INSERT_VERY_STRONG_PASSWORD>'
+export RUST_LOG='debug,sqlx=warn,hyper=warn,hyper_util=warn'

tools/cleanup

@@ -0,0 +1,16 @@
+#!/bin/bash
+
+##
+#  This file is part of prose-pod-system
+#
+#  Copyright 2024, Prose Foundation
+##
+
+set -e
+
+PROSE_POD_SYSTEM_DIR=${PROSE_POD_SYSTEM_DIR:-"$(dirname "$0")"/..};
+SERVER_ROOT=${SERVER_ROOT:-"${PROSE_POD_SYSTEM_DIR:?}"/server/pod};
+
+echo '' > "${PROSE_POD_SYSTEM_DIR}"/database.sqlite;
+rm -rf "${SERVER_ROOT}"/etc/prosody/prosody.cfg.lua || :;
+rm -rf "${SERVER_ROOT}"/var/lib/prosody/*%2e* || :;