Missing documentation/templates for PowerSync setup (config-powersync, sync_rules, required env vars), Android app now no longer working

[janekkkk]

After pulling the latest docker-compose.yml, I noticed it now includes services/powersync.yaml, services/postgres.yaml, and services/redis.yaml, adding a new powersync service. However, getting this actually working required a lot of trial and error, since several required pieces aren't documented anywhere I could find.
Impact: the Android/iOS app is currently unusable for me
Since this update, logging in via the official wger app shows a "Sync service unavailable" error and blocks further use of the app entirely — even though the web client works fine. There doesn't seem to be a way to dismiss this and use the app without PowerSync configured, so anyone updating their self-hosted instance loses app access until PowerSync is fully and correctly set up.

1. No example config-powersync/powersync.yaml / sync_rules.yaml
   services/powersync.yaml mounts ./config-powersync:/config:ro, but this directory and its contents (powersync.yaml, referencing sync_rules.yaml) aren't provided as an example/template anywhere in this repo. Since the PowerSync service won't start without a valid config here, new users have no starting point.
2. Required env vars aren't documented for this feature
   To get this working I had to reverse-engineer the following from the wger source code:

JWT_PRIVATE_KEY / JWT_PUBLIC_KEY — generated via python3 manage.py generate-jwt-keys (this part is mentioned in the Settings docs page, but not connected anywhere to the PowerSync feature)
PS_STORAGE_PG_URI — needed for python3 manage.py setup-powersync-storage, not documented at all
PS_JWKS_URL — set automatically in services/powersync.yaml, but its dependency on JWT_PUBLIC_KEY isn't obvious

3. Postgres replication requirements not called out
   PowerSync requires logical replication (wal_level=logical) on the source Postgres instance. The updated services/postgres.yaml does set this, but if someone has an older standalone db service definition (pre-include refactor), nothing tells them they need to update it or that this is why PowerSync won't replicate.
4. No mention of any of this in the production deployment docs
   The production/docker.html docs page in the wger docs doesn't mention PowerSync at all, and administration/powersync.html only covers maintenance (compaction), assuming a working setup already exists.
   Suggested fix:

Add a minimal working example under config-powersync/ (e.g. powersync.yaml.example, sync_rules.yaml.example) covering the tables already registered via wger.utils.powersync.PowerSyncHandler subclasses
Add a short "Setting up PowerSync" section to the production Docker docs covering the required env vars and the setup-powersync-storage command
Cross-link the JWT key generation step to the PowerSync feature, not just SimpleJWT/allauth
Consider whether the app should be able to gracefully fall back to "online only" mode instead of blocking login entirely when the sync service is unreachable

Happy to help test/verify a draft of this if useful — happy to share my own working .env/config once I get it fully running.

Version: 2.7.0a1

[rolandgeider]

hey!

yes, the app now only syncs via the new service, supporting both paths is sadly not something we can afford.

The sync rules are in the repo and are referenced by the service. Same for the other envs, did you perhaps have out some older version checked out?

As for the specific upgrade steps they are alyways in the backend repo, but this was probably the most disruptive one we ever had, most of them should be pretty straight forward

[reggiano]

I also cannot get PowerSync to start. I followed the upgrade steps, but no luck. The log for the PowerSync container states as follows:

"level":"error","message":"Fatal startup error - exiting with code 150. Could not collect config using FileSystem method. Caught exception: Error: Config file path /config/powersync.yaml was specified, but the file does not exist.","stack":"Error: Could not collect config using FileSystem method. Caught exception: Error: Config file path /config/powersync.yaml was specified, but the file does not exist.\n at CompoundConfigCollector.collectBaseConfig (file:///app/packages/service-core/dist/util/config/compound-config-collector.js:164:23)\n at async CompoundConfigCollector.collectConfig (file:///app/packages/service-core/dist/util/config/compound-config-collector.js:27:28)\n at async Module.loadConfig (file:///app/packages/service-core/dist/util/config.js:20:20)\n at async startUnifiedRunner (file:///app/service/lib/runners/unified-runner.js:10:20)\n at async Command. (file:///app/packages/service-core/dist/entry/commands/start-action.js:12:9)\n at async Command.parseAsync (/app/node_modules/.pnpm/commander@12.1.0/node_modules/commander/lib/command.js:1092:5)\n at async runProgram (file:///app/packages/service-core/dist/entry/cli-entry.js:31:17)","timestamp":"2026-06-24T20:24:12.949Z"}

[rolandgeider]

@reggiano luckily this time the error is very specific (powersync isn't always... as straightforward). How does the powersync service look in the docker compose? Does the ./config-powersync folder exist and has all the config files?

[reggiano]

@rolandgeider sorry for the late reply. I am running wger in a Synology NAS via Container Manager. I was having some issues with the include block at the end of docker-compose.yaml (apparently some parameters in postgres.yaml were causing conflicts). With some help of the AI, decided to discard the include block and integrate the variables directly in the docker-compose.yaml and powersync.yaml (I know, risky from my part). Here's how the powersync part looks on docker-compose.yaml:

  powersync:
    image: journeyapps/powersync-service:latest
    restart: unless-stopped
    env_file:
      - /volume2/docker/wger/config/prod.env
    environment:
      - POWERSYNC_CONFIG_PATH=/config/powersync.yaml
      # FORCED PASS-THROUGH: Maps the variables explicitly for the YAML parser
      - PS_DATABASE_URI=${PS_DATABASE_URI}
      - PS_STORAGE_PG_URI=${PS_STORAGE_PG_URI}
      - PS_PORT=${PS_PORT}
      - PS_JWKS_URL=${PS_JWKS_URL}
    volumes:
      # Maps your new Synology folder paths directly into the container
      - /volume2/docker/wger/services/config-powersync:/config:ro
    ports:
      - "8080:8080"
    healthcheck:
      test: [ "CMD", "node", "-e", "fetch('http://localhost:8080/probes/liveness').then(r => r.ok ? process.exit(0) : process.exit(1)).catch(() => process.exit(1))" ]
      interval: 10s
      timeout: 2s
      retries: 3
      start_period: 30s
    depends_on:
      db:
        condition: service_healthy
      web:
        condition: service_healthy

and the powersync.yaml file:

services:
  powersync:
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped

    image: docker.io/journeyapps/powersync-service:latest
    logging:
      driver: json-file
      options:
        max-size: 10m
        max-file: 3

    command: ["start", "-r", "unified"]

    volumes:
      - ./config-powersync:/config:ro

    env_file:
      - ../config/prod.env

    environment:
      POWERSYNC_CONFIG_PATH: /config/powersync.yaml
      PS_JWKS_URL: http://web:8000/api/v2/powersync-keys

    expose:
      # API
      - 8080

      # Prometheus metrics
      - 9090

Eventually I managed to start all containers, and after running python3 manage.py generate-jwt-keys and pasting the keys in prod.env (double checked everything) and wger-web-1 doesn't start anymore. Restored the default keys and everything launched normally. Decided to check from the app and got syncresponseexception: 405 not allowed. Would you mind pointing at what i am doing wrong? :)

[rolandgeider]

I would suspect that there's some formatting with the keys that breaks the container. I'm not sure if synology does something with them, but for regular docker you would just paste them as the script generates them, without any quotation marks or anything. And if you are not exposing the server to the internet, you can keep them for the moment.

As for the 405, this looks like the app isn't reaching the powersync service properly. If you open /api/v2/powersync-token what does powersync_url return and can you open it? (you should get an PSYNC_S2002 error json about the path not existing). You need to reverse proxy the /ps path to the powersync service

[reggiano]

powersync_url returns "http://my_nas_IP:8800/ps" and opening it in my browser gives me this:

Indeed my nginx.conf was missing the Reverse proxy for the PowerSync service. I added that block and updated the prod.env for powersync as follows:

# Other powersync settings
PS_STORAGE_PG_URI=postgres://powersync_storage:powersync_password@db:5432/wger
PS_PORT=8080
POWERSYNC_URL_PATH='ps'
# The full url for the powersync service, overrides POWERSYNC_URL_PATH if set. Only
# set if you know what you are doing and have a very different setup
POWERSYNC_URL=http://my_nas_IP:8800/ps

Now the app shows a 404 error. What am I missing to set the reverse proxy?

[rolandgeider]

I just noticed (and I'm not sure if it's the default or if we explicitly need it), but it seems you forgot the command for the powersync service (command: ["start", "-r", "unified"])

Also, can you try and see if nginx can reach the service at all? docker compose exec nginx curl -i http://powersync:8080/probes/liveness

[reggiano]

I have [command ](command: ["start", "-r", "unified"]) in my powersync.yaml file, as I already posted in #156 (comment). Also nginx can reach powersync:

HTTP/1.1 200 OK                                                                  
access-control-allow-origin: *                                                   
access-control-expose-headers: Content-Type                                      
content-type: application/json; charset=utf-8                                    
content-length: 69                                                               
Date: Sun, 05 Jul 2026 16:07:35 GMT                                              
Connection: keep-alive                                                           
Keep-Alive: timeout=72

Since my last comment, I tried commenting out POWERSYNC_URL=http://my_nas_IP:8800/ps to employ POWERSYNC_URL_PATH=ps, and again I get 405 not allowed