This starter proves the AppThrust managed PostgreSQL path:
- AppThrust injects
DATABASE_URLthroughComponentConnection. - The initial schema is applied through
DatabaseChange. - The Next.js app reads and writes
appthrust_demo_messages.
The Docker image is a code-only artifact run by the AppThrust Managed Runtime
nodejs-24, which supplies Node.js and launches node server.js in
/workspace/app as UID/GID 1000 with a writable .next/cache volume. It is not
runnable standalone with docker run. Local development is unchanged: use
npm run dev.
The app does not run migrations on startup. For local development, apply
db/migrations/0001_init.sql to your PostgreSQL database, then set:
DATABASE_URL=postgresql://app:password@localhost:5432/appRun locally:
npm install
npm run devThe platform probes GET /healthz for startup and liveness, and GET / for readiness. Keep /healthz static and database-independent so startup and liveness do not depend on database availability.
App roles let a Project admin decide which groups and people may view, edit or manage each kind of item in this app. The template does not include them. Add them only to an app that needs them: the helper package comes from GitHub Packages, which requires a token to install even though the package is public.
Create .npmrc (it holds a variable reference; never commit a token):
@appthrust:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}Install with a token that has read:packages:
gh auth refresh --scopes read:packages # once
NODE_AUTH_TOKEN=$(gh auth token) npm install --save-exact @appthrust/app-accessFrom now on npm ci needs NODE_AUTH_TOKEN too. npm run dev, lint and
build do not.
In .github/workflows/deploy.yml, uncomment the secrets: lines of the
"Build and push Docker images" step. The Dockerfile already reads that build
secret.
lib/app-access.ts:
import "server-only";
import { headers } from "next/headers";
import {
fromEnv,
type AppAccess,
type AppAccessClient,
} from "@appthrust/app-access";
let client: AppAccessClient | undefined;
// One client per server process so requests share its caches. "PLATFORM" is
// the environment prefix of a platform connection named "platform". Throws
// when the connection is missing: a half-configured app fails closed.
export function appAccess(): AppAccessClient {
client ??= fromEnv("PLATFORM", {
application: process.env.APP_ACCESS_APPLICATION?.trim() ?? "",
});
return client;
}
// Permissions of the signed-in user for the current request, for Server
// Actions and Server Components.
export async function currentAccess(): Promise<AppAccess> {
return appAccess().getAppAccess(await headers());
}Check a permission on the server before every protected read or write; hiding
a button is not authorization. For example, to let only editors save messages
in app/actions.ts:
import { currentAccess } from "@/lib/app-access";
export async function createMessage(formData: FormData) {
// Throws Unauthenticated (not signed in), Forbidden (not permitted) or
// Unavailable (platform unreachable); nothing below runs.
(await currentAccess()).require("messages:write");
// ...save the message
}A Route Handler passes its Request and maps those errors to 401 / 403 / 503
with toResponse:
import { toResponse } from "@appthrust/app-access";
import { appAccess } from "@/lib/app-access";
export async function GET(request: Request) {
try {
const access = await appAccess().getAppAccess(request);
access.require("messages:read");
return Response.json({ canWrite: access.has("messages:write") });
} catch (error) {
return toResponse(error);
}
}-
In the Dashboard, open the Application's Access tab, define the item types and roles, and assign roles to groups or people.
-
Require sign-in on the published endpoint and add a platform connection to the web component:
apth publishes access set <project> <publish> --mode Authenticated apth component-connections create <project> <web component> --destination-platform --name platform
-
Set
APP_ACCESS_APPLICATIONto the Application resource name:apth apps env set <application> APP_ACCESS_APPLICATION=<application>
Permission names such as messages:write are the ones the Access tab shows
for each item type and level. Role changes reach the app within about a
minute; the first activation can take up to five minutes for users who were
already signed in. See the
@appthrust/app-access README
for errors and caching.