Most self-hosting problems come down to a handful of misconfigurations. Start here before opening an issue.
Appsweet exits immediately on start
Three variables are read while the process is booting, and a missing one stops it before it binds anything:
APPSWEET_DATABASE_URL— the log line isAPPSWEET_DATABASE_URL is required. A database that is not accepting connections yet looks much the same from outside.APPSWEET_OIDC_ISSUERandAPPSWEET_OIDC_CLIENT_ID—APPSWEET_OIDC_ISSUER is required, or the same for the client ID. These are not sign-in-time settings: the OIDC configuration is loaded during startup, so a container given only a database URL exits here rather than starting and failing later at the login screen.
Check the container logs first; the error names the variable outright.
Migrations fail on a fresh database
If the logs stop at CREATE EXTENSION IF NOT EXISTS vector — usually reported as
extension "vector" is not available — the Postgres you pointed at cannot install pgvector.
That is the first migration Appsweet runs, so nothing else gets a chance.
The stock postgres image does not ship the extension. Use pgvector/pgvector:pg16, or on
a managed provider enable the vector extension for that database before starting Appsweet.
The port is mapped but nothing answers
APPSWEET_BIND_ADDR defaults to 127.0.0.1:3000, which inside a container is the
container's own loopback — the published port reaches nothing. Set it to 0.0.0.0:3000 and
let the container runtime or your proxy decide what is exposed.
Sign-in never comes back
The redirect URIs are derived from APPSWEET_PUBLIC_BASE_URL, so if that does not match the
URL the browser is actually on, the round trip ends somewhere unreachable. Set it to the
public URL, and make sure APPSWEET_OIDC_ISSUER and APPSWEET_OIDC_CLIENT_ID both point at
the identity provider you are really using.
File uploads fail
Object storage is required for a real deployment, but the backend does not refuse to start
without it: it comes up with files disabled and everything else working, and does not log
anything about it. So if files are the only broken part, the likely cause is that
APPSWEET_S3_ENDPOINT was never set. An endpoint with no access key, no secret key, or an
unparseable APPSWEET_S3_PRESIGN_TTL_SECS disables files too, but that case does log —
storage configuration is invalid; files disabled. Credentials that are present but wrong
fail later, at the upload itself. Where clients cannot reach the internal endpoint, set
APPSWEET_S3_PUBLIC_ENDPOINT as well, since presigned URLs are minted against it.
The image will not pull
The appsweet-backend package is private for the duration of the controlled beta. Without
a ghcr.io credential scoped to read packages, the registry reports the image as not found
rather than as forbidden — which reads like a typo in the reference but is not one.