Building apps

App structure & app.json

An Astrodock app is just a normal folder of code plus one small file, app.json, that tells the platform what to build and how to run it. This page covers the folder layout Astrodock auto-detects, the handful of rules your server must follow, and every field in app.json.

The app layout

You don't configure a router or a build pipeline. You arrange your files in one of a few shapes, and the runner figures out the rest:

The most common shape is the first one — a frontend and a server living side by side:

my-app/
├── app.json            ← the manifest (always)
├── app/                ← frontend (e.g. Vite/React); builds to app/dist/
│   ├── package.json
│   └── src/…
└── server/             ← Express server
    ├── package.json
    └── server.js       ← entry point

The frontend builds to app/dist/, and Astrodock serves that static output at https://<subdomain>.<base-domain> with an SPA fallback (unknown paths return index.html so client-side routing works). Anything under /api/* is proxied to your server instead. For Docker apps there is no app/ + server/ split — your container serves everything; see Dockerfile apps.

The hard rules for a server

If your app has a server, it must follow four rules. They're small, and breaking one is the usual reason a deploy looks healthy but doesn't work:

1. Bind process.env.ASTRODOCK_PORT

   The platform tells your server which port to listen on. Don't hardcode 3000. An unprefixed PORT alias is also provided for convenience, but prefer the explicit one.

   const PORT = process.env.ASTRODOCK_PORT || process.env.PORT || 3000;
   app.listen(PORT);

2. Put every route under /api

   Caddy only proxies /api/* to your server; everything else is the static frontend. A route at /login will 404 — it has to be /api/login.

3. Answer GET /health with a 200

   After every deploy the platform probes your server. A 200 from /health marks the deploy healthy. (This is the one route that lives outside /api.)

   app.get('/health', (req, res) => res.json({ status: 'ok' }));

4. Read config from injected env — never hardcode

   Database URLs, storage credentials, auth secrets, and your own declared variables all arrive as environment variables at deploy time. Read them from process.env; never paste a secret into your code or commit it.

A full app.json, annotated

Here is a complete manifest for a frontend + server app that uses platform login, the bundled database, and one app-specific variable. The notes after each block explain what it does — the file itself is plain JSON with no comments.

{
  "schemaVersion": "1",

  "slug": "invoice-tool",
  "name": "Invoice Tool",
  "description": "Generate and store client invoices",
  "subdomain": "invoices",

  "source": {
    "branch": "main",
    "repoPath": ""
  },

  "runtime": {
    "type": "node",
    "buildCommand": "npm run build"
  },

  "auth":     { "mode": "platform" },
  "database": { "mode": "internal" },
  "storage":  { "mode": "internal" },

  "env": [
    { "key": "OPENAI_API_KEY", "secret": true, "required": true,
      "description": "Used to draft line items" },
    { "key": "INVOICE_PREFIX", "secret": false, "required": false,
      "default": "INV-", "description": "Prefix for invoice numbers" }
  ]
}

• slug is the app's permanent identity — it names the process, the internal database, and the storage prefix. It can't change later.
• subdomain is where the app lives: invoices.<base-domain>. You can change it later (it triggers a new certificate).
• runtime.type: "node" means the Node buildpack; buildCommand is how the frontend is built (it defaults to npm run build, so this line is optional).
• auth, database, and storage are the three resource modes — see below.
• env declares your own variables by name. Secret values never go in this file; you set them with astrodock set-secret or in the dashboard.

Field reference

The full schema reference (with types and defaults for every nested field) lives on app.json & env reference. This is the quick version:

Resource modes

Each app picks how it wants a database and object storage — and whether the platform handles login. The choice is pure configuration: your code reads the same environment variables either way, so moving from the bundled database to a hosted one later is a value change, not a code change.

With internal, everything is provisioned for you. With external, the deploy is blocked until you've set the credentials (the required-variable gate). The details for each:

• External database — bring your own Postgres.
• External storage — bring your own S3-compatible bucket.

Adding login with platform auth

Set "auth": { "mode": "platform" } and the platform injects everything your server needs to verify users it manages: ASTRODOCK_AUTH_URL, ASTRODOCK_APP_ID, ASTRODOCK_APP_SECRET, and ASTRODOCK_APP_JWT_SECRET.

The flow is: your frontend posts an email + password to your own /api/login, your server asks the platform "are these valid for me?", and on success you mint your own session. Here's the core of it, lifted from the starter app:

app.post('/api/login', async (req, res) => {
  const { email, password } = req.body || {};

  // Ask the control plane to verify the credentials for THIS app.
  const verifyRes = await fetch(`${process.env.ASTRODOCK_AUTH_URL}/verify`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      email,
      password,
      appId: process.env.ASTRODOCK_APP_ID,
      appSecret: process.env.ASTRODOCK_APP_SECRET
    })
  });

  if (verifyRes.status === 401) return res.status(401).json({ error: 'Invalid credentials' });
  if (verifyRes.status === 403) return res.status(403).json({ error: 'No access to this app' });
  if (!verifyRes.ok) return res.status(502).json({ error: 'Auth error' });

  const user = await verifyRes.json(); // { userId, email, name }

  // Mint your own session — here, a JWT signed with the injected secret.
  const session = jwt.sign(
    { sub: user.userId, email: user.email, name: user.name },
    process.env.ASTRODOCK_APP_JWT_SECRET,
    { expiresIn: '7d' }
  );
  res.cookie('session', session, { httpOnly: true, sameSite: 'lax', secure: true });
  res.json({ user });
});

Next steps

• How a deploy actually runs: The deploy lifecycle
• Ship a non-Node runtime: Dockerfile apps
• Every field and variable, precisely: app.json & env reference

Related

• Deploy your first app
• Manage users & access
• External database · External storage