feat(platforms): add platforms.sh wrapper

Author: PromiseFru

.gitignore

@@ -7,7 +7,9 @@ platforms/available/*
 *.sh
 !install.sh
 !manage.sh
+!platforms.sh
 !docker-entrypoint.sh
+!scripts/*.sh
 credentials.json
 logs/
 logos/*.svg

Dockerfile

@@ -42,7 +42,7 @@ RUN --mount=type=cache,sharing=locked,target=/var/cache/apt \
 COPY --from=builder /venv /venv
 COPY --from=builder /publisher /publisher
 
-RUN chmod +x /publisher/docker-entrypoint.sh
+RUN chmod +x /publisher/docker-entrypoint.sh /publisher/scripts/run.sh
 
 ENV PATH="/venv/bin:${PATH}"
 ENV MODE=production

INSTALL.md

@@ -75,12 +75,12 @@ Edit `.env` (see [Configuration](#configuration) below).
 
 ### Application Directories
 
-Create the directories referenced in `.env` and assign ownership to the service user. Replace `$SERVICE_USER` with your username (or `relaysms` if you created that account):
+Create the directories referenced in `.env` and assign ownership to the service user. Replace `$SERVICE_USER` with your username (or `relaysms` if you created that account). By default, the SQLite database, Celery broker/result/beat files all live under `data/` and the adapters live under `platforms/`:
 
 ```bash
 SERVICE_USER=$(whoami)
 
-# SQLite database directory (default)
+# SQLite database + Celery broker/result/beat schedule directory (default)
 sudo mkdir -p data
 sudo chown "$SERVICE_USER": data && sudo chmod 750 data
 
@@ -90,7 +90,13 @@ sudo chown "$SERVICE_USER": platforms/adapters platforms/adapters_venv platforms
 sudo chmod 750 platforms/adapters platforms/adapters_venv platforms/adapters_assets
 ```
 
-If you changed any path variables in `.env`, create those directories instead.
+If you changed any of the following path variables in `.env`, create the parent directory of each instead, and see [Install Services](#install-services) below for how to keep the systemd sandbox in sync:
+
+- `SQLITE_DATABASE_PATH`
+- `CELERY_BROKER_DB_PATH`, `CELERY_RESULT_DB_PATH` (sqlite broker only)
+- `CELERY_BEAT_SCHEDULE_PATH`
+- `PLATFORMS_ADAPTERS_DIR`, `PLATFORMS_ADAPTERS_VENV_DIR`, `PLATFORMS_ADAPTERS_ASSETS_DIR`
+- `PLATFORMS_REGISTRY_FILE`
 
 ### Run Migrations
 
@@ -101,13 +107,26 @@ make migrate-up
 
 ### Install Services
 
+The provided service unit files use a `__RW_PATHS__` placeholder for `ReadWritePaths=` instead of a hardcoded path, since all the paths listed above can be changed in `.env`. Substitute it with the actual, resolved directories before installing (`install.sh` does this for you automatically):
+
 ```bash
+RW_PATHS="$(pwd)/data $(pwd)/platforms/adapters $(pwd)/platforms/adapters_venv $(pwd)/platforms/adapters_assets"
+
+sudo sed \
+    -e "s/User=relaysms/User=$SERVICE_USER/" \
+    -e "s|__RW_PATHS__|$RW_PATHS|" \
+    -i relaysms-publisher-rest.service relaysms-publisher-grpc.service \
+       relaysms-publisher-worker.service relaysms-publisher-beat.service
+
 sudo cp relaysms-publisher.target relaysms-publisher-*.service /etc/systemd/system/
 sudo systemctl daemon-reload
 sudo systemctl enable relaysms-publisher.target
 sudo systemctl start relaysms-publisher.target
 ```
 
+> [!WARNING]
+> All four services (`rest`, `grpc`, `worker`, `beat`) run with `ProtectSystem=strict` and `ProtectHome=true`, which make the entire filesystem read-only except for paths explicitly listed in `ReadWritePaths`. If you moved the SQLite database, Celery broker/result/beat files, or any adapter directory outside the installation root, add each resolved parent directory to `RW_PATHS` above - a path missing from `ReadWritePaths` will silently fail to write.
+
 ## Service Management
 
 ```bash
@@ -122,6 +141,22 @@ sudo systemctl start relaysms-publisher.target
 ./manage.sh uninstall   # Remove installation
 ```
 
+## Managing Platform Adapters
+
+Use `platforms.sh` instead of calling `python3 -m platforms.cli` directly. It automatically resolves the install directory, loads `.env`, uses the project venv, and runs as the correct service user so adapter files and the registry never end up with mismatched ownership:
+
+```bash
+./platforms.sh add <GITHUB_URL>          # Add an adapter
+./platforms.sh remove <NAME>             # Remove an adapter
+./platforms.sh update [NAME] [--install] # Update one or all adapters
+./platforms.sh list                      # List registered adapters
+./platforms.sh recover                   # Rebuild registry from disk
+./platforms.sh env                       # Show resolved paths and service user
+./platforms.sh shell                     # Open a shell as the service user with .env loaded
+```
+
+See [Platforms Documentation](platforms/README.md) for details.
+
 ## Configuration
 
 Edit `/opt/relaysms/relaysms-publisher/.env`:
@@ -177,20 +212,46 @@ DATABASE_FIELD_ENCRYPTION_KEY=<64 hex chars>
 > - The `DATABASE_ENCRYPTION_KEY` is used to encrypt the entire database at rest (SQLite only).
 > - The `DATABASE_FIELD_ENCRYPTION_KEY` is used to encrypt specific sensitive fields in the database.
 
+### Celery (Worker / Beat)
+
+```bash
+# Broker/backend type: sqlite | redis | rabbitmq
+CELERY_BROKER_TYPE=sqlite
+
+# sqlite (default)
+CELERY_BROKER_DB_PATH=data/celery_broker.db
+CELERY_RESULT_DB_PATH=data/celery_results.db
+
+# redis
+# CELERY_REDIS_URL=redis://localhost:6379/0
+
+# rabbitmq
+# CELERY_RABBITMQ_URL=amqp://user:pass@localhost:5672//
+
+CELERY_BEAT_SCHEDULE_PATH=data/celerybeat-schedule
+```
+
+> [!NOTE]
+> If you move any of the `sqlite`-backed Celery paths outside the default `data/` directory, remember to add the new parent directory to `ReadWritePaths` when [installing services](#install-services), since the worker and beat units run under `ProtectSystem=strict`.
+
 ### Platform Adapters
 
 ```bash
 PLATFORMS_ADAPTERS_DIR=platforms/adapters
 PLATFORMS_ADAPTERS_VENV_DIR=platforms/adapters_venv
 PLATFORMS_ADAPTERS_ASSETS_DIR=platforms/adapters_assets
+PLATFORMS_REGISTRY_FILE=platforms/registry.json
 ```
 
 See [Platforms Documentation](platforms/README.md) and individual adapter READMEs for setup.
 
+> [!NOTE]
+> `PLATFORMS_REGISTRY_FILE` is written to by `platforms.cli add|remove|update` and read by the running services at startup. Always run `platforms.cli` as the service user (see [Platforms Documentation](platforms/README.md)) so the registry stays writable and readable across CLI runs and service restarts.
+
 | Path | Description |
 |---|---|
 | `/opt/relaysms/relaysms-publisher/` | Installation root |
 | `/opt/relaysms/relaysms-publisher/.env` | Configuration (root:relaysms, 640) |
-| `/opt/relaysms/relaysms-publisher/data/` | SQLite database (relaysms, 750) |
+| `/opt/relaysms/relaysms-publisher/data/` | SQLite database, Celery broker/result/beat files (relaysms, 750) |
 | `/opt/relaysms/relaysms-publisher/platforms/` | Adapter data (relaysms, 750) |
 | `/etc/systemd/system/relaysms-publisher*` | Service units |

README.md

@@ -60,9 +60,8 @@ make build-setup
 # Run database migrations
 make migrate-up
 
-# Start services
-python3 grpc_server.py        # Terminal 1
-fastapi dev app.py             # Terminal 2
+# Start gRPC, REST API, Celery worker, and Celery beat together
+./scripts/run.sh
 ```
 
 ### Docker
@@ -79,14 +78,17 @@ cp template.env .env
 docker run -d \
   --name relaysms-publisher \
   --env-file .env \
-  -p 9000:9000 \
+  -p 16000:16000 \
   -p 6000:6000 \
   -v $(pwd)/data:/publisher/data \
+  -v $(pwd)/platforms:/publisher/platforms \
   relaysms-publisher:latest
 ```
 
+The container entrypoint runs pending database migrations, then starts the gRPC server, REST API, Celery worker, and Celery beat scheduler together (via `scripts/run.sh`).
+
 > [!TIP]
-> Update `GRPC_HOST=0.0.0.0` and `HOST=0.0.0.0` in `.env` for external container access.
+> `HOST` and `GRPC_HOST` default to `0.0.0.0` inside the container so it's reachable from outside. If your `.env` file explicitly sets `HOST=127.0.0.1` or `GRPC_HOST=127.0.0.1` (e.g. copied unedited from `template.env`), it will override the container default and the services won't be reachable - remove or update those lines in `.env` for Docker deployments.
 
 ## Configuration
 

docker-entrypoint.sh

@@ -2,10 +2,11 @@
 
 set -e
 
-python3 -u grpc_server.py &
-exec python3 -m uvicorn app:app \
-    --host "${HOST:-0.0.0.0}" \
-    --port "${PORT:-80}" \
-    --workers "${WORKERS:-4}" \
-    --proxy-headers \
-    --forwarded-allow-ips "*"
+export HOST="${HOST:-0.0.0.0}"
+export PORT="${PORT:-80}"
+export WORKERS="${WORKERS:-4}"
+export GRPC_HOST="${GRPC_HOST:-0.0.0.0}"
+
+python3 -m alembic upgrade head
+
+exec ./scripts/run.sh

docs/rest.md

@@ -129,7 +129,7 @@ Displays the OAuth2 callback parameters returned by a platform. Intended as a re
 
 **Query Parameters:** All query parameters forwarded by the OAuth provider (e.g., `code`, `state`) are captured and displayed in an HTML table.
 
-**Response:** `200 OK` — HTML page listing all callback parameters.
+**Response:** `200 OK`, HTML page listing all callback parameters.
 
 **Error Responses:**
 

install.sh

@@ -132,34 +132,60 @@ setup_env() {
   log "Edit $INSTALL_DIR/.env before starting services"
 }
 
-create_app_directories() {
-  log "Creating application directories"
+# Resolves app data directories from .env (absolute or relative to
+# INSTALL_DIR) into the global RW_DIRS array. Shared by create_app_directories
+# and install_services so systemd ReadWritePaths always matches reality.
+resolve_app_directories() {
   local envfile="$INSTALL_DIR/.env"
   [ -f "$envfile" ] || error ".env not found"
 
-  local sqlite_path adapters_dir adapters_venv adapters_assets
+  local sqlite_path celery_broker_path celery_result_path celery_beat_path
+  local adapters_dir adapters_venv adapters_assets registry_file
   sqlite_path=$(read_env_var "SQLITE_DATABASE_PATH" "$envfile")
+  celery_broker_path=$(read_env_var "CELERY_BROKER_DB_PATH" "$envfile")
+  celery_result_path=$(read_env_var "CELERY_RESULT_DB_PATH" "$envfile")
+  celery_beat_path=$(read_env_var "CELERY_BEAT_SCHEDULE_PATH" "$envfile")
   adapters_dir=$(read_env_var "PLATFORMS_ADAPTERS_DIR" "$envfile")
   adapters_venv=$(read_env_var "PLATFORMS_ADAPTERS_VENV_DIR" "$envfile")
   adapters_assets=$(read_env_var "PLATFORMS_ADAPTERS_ASSETS_DIR" "$envfile")
+  registry_file=$(read_env_var "PLATFORMS_REGISTRY_FILE" "$envfile")
 
-  _make_dir() {
-    local dir="$1" label="${2:-}"
+  RW_DIRS=()
+  _resolve_dir() {
+    local dir="$1"
     [ -z "$dir" ] && return
     [[ "$dir" = /* ]] || dir="$INSTALL_DIR/$dir"
-    mkdir -p "$dir"
-    chown "$SERVICE_USER:" "$dir"
-    chmod 750 "$dir"
-    log "  $dir${label:+ ($label)}"
+    # Skip duplicates (e.g. celery paths sharing the same directory as sqlite).
+    local existing
+    for existing in "${RW_DIRS[@]}"; do
+      [ "$existing" = "$dir" ] && return
+    done
+    RW_DIRS+=("$dir")
   }
 
   if [ -n "$sqlite_path" ] && [ "$sqlite_path" != ":memory:" ]; then
-    _make_dir "$(dirname "$sqlite_path")" "sqlite"
+    _resolve_dir "$(dirname "$sqlite_path")"
   fi
+  [ -n "$celery_broker_path" ] && _resolve_dir "$(dirname "$celery_broker_path")"
+  [ -n "$celery_result_path" ] && _resolve_dir "$(dirname "$celery_result_path")"
+  [ -n "$celery_beat_path" ] && _resolve_dir "$(dirname "$celery_beat_path")"
+  _resolve_dir "$adapters_dir"
+  _resolve_dir "$adapters_venv"
+  _resolve_dir "$adapters_assets"
+  [ -n "$registry_file" ] && _resolve_dir "$(dirname "$registry_file")"
+}
 
-  _make_dir "$adapters_dir" "adapters"
-  _make_dir "$adapters_venv" "adapters venv"
-  _make_dir "$adapters_assets" "adapters assets"
+create_app_directories() {
+  log "Creating application directories"
+  resolve_app_directories
+
+  local dir
+  for dir in "${RW_DIRS[@]}"; do
+    mkdir -p "$dir"
+    chown "$SERVICE_USER:" "$dir"
+    chmod 750 "$dir"
+    log "  $dir"
+  done
 }
 
 run_migrations() {
@@ -177,9 +203,21 @@ run_migrations() {
 install_services() {
   log "Installing systemd services"
   cd "$INSTALL_DIR"
-  for svc in relaysms-publisher.target relaysms-publisher-rest.service relaysms-publisher-grpc.service; do
+
+  resolve_app_directories
+  local rw_paths
+  rw_paths=$(
+    IFS=' '
+    echo "${RW_DIRS[*]}"
+  )
+  [ -n "$rw_paths" ] || error "No application directories resolved for ReadWritePaths"
+
+  for svc in relaysms-publisher.target relaysms-publisher-rest.service relaysms-publisher-grpc.service relaysms-publisher-worker.service relaysms-publisher-beat.service; do
     [ -f "$svc" ] || error "Service file not found: $svc"
-    sed "s/User=relaysms/User=$SERVICE_USER/" "$svc" >"/etc/systemd/system/$svc" ||
+    sed \
+      -e "s/User=relaysms/User=$SERVICE_USER/" \
+      -e "s|__RW_PATHS__|$rw_paths|" \
+      "$svc" >"/etc/systemd/system/$svc" ||
       error "Failed to install $svc"
   done
   systemctl daemon-reload || error "Failed to reload systemd"
@@ -205,6 +243,7 @@ main() {
   log "Installation complete"
   log "  Config : $INSTALL_DIR/.env"
   log "  Manage : $INSTALL_DIR/manage.sh {start|stop|restart|status|logs|update}"
+  log "  Platforms : $INSTALL_DIR/platforms.sh {add|remove|update|list|recover|env|shell}"
 }
 
 main "$@"