> ## Documentation Index
> Fetch the complete documentation index at: https://docs.postsider.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting and operations

> Health checks, logs, failed publishing, upgrades, and restore checks for PostSider OSS.

## Check service health

From the repository directory:

```bash theme={null}
docker compose ps
curl -fsS http://127.0.0.1:5000/api/health
docker compose exec postsider wget -qO- http://localhost:3002/health/workers
```

The API health response should report database, Redis, and Temporal as `ok`. The worker response should report running and healthy workers. A healthy frontend does not prove scheduled publishing works.

## Read logs

```bash theme={null}
docker compose logs --tail=200 postsider
docker compose logs --tail=200 temporal
docker compose logs --tail=200 postgres
```

For a scheduled post, inspect the `main` Temporal task queue and the orchestrator logs. Do not add Node-only imports to Temporal workflow code; a broken workflow bundle can stop workers while the dashboard remains available.

## Monitoring and alerting

* `/api/health` reports `redis`, `database`, and `temporal` status and returns **503** when any of them is degraded (not a green 200).
* `/health/workers` inside the container reports per-queue worker state and 503s when a worker is not polling - the `main` queue carries every publish workflow.
* The optional Temporal UI at `127.0.0.1:8080` (SSH tunnel) shows workflows and the `main` task queue.
* Inspect the queue with the Temporal CLI:
  ```bash theme={null}
  docker compose exec temporal temporal task-queue describe --task-queue main --address temporal:7233
  ```
  **0 pollers** means the workers are down and scheduled posts will pile up in `QUEUE` without errors.
* Point an external uptime monitor at `/api/health` (HTTP mode) and `/health/workers` if reachable. On self-hosted instances set up log rotation and a disk/restart alert.

## A post missed its scheduled time

1. Check `/api/health`.
2. Check `/health/workers` from inside the application container.
3. Confirm the post is not in `ERROR` state.
4. Inspect `docker compose logs postsider` for Temporal or provider errors.
5. Check the connected channel and provider OAuth token.

## Upgrade safely

Back up both PostgreSQL databases, MinIO media, and `.env` first. Then deploy a tagged source release:

```bash theme={null}
git fetch --tags origin
git checkout v1.0.1
docker compose up -d --build --wait
```

Run the health checks again after the upgrade. Do not use `docker compose pull` as an application update; the OSS application is built from the checked-out source.

## Restore checklist

Restore PostgreSQL, Temporal PostgreSQL, MinIO, and the exact `.env` used by the instance. `ENCRYPTION_KEY` is required to decrypt stored provider credentials. After restoring, verify API health, worker health, a media object, and a test scheduled post before reopening the instance to users.