app-run-and-deploy

Files (1)

• SKILL.md

SKILL.md (first lines)

# Running and Deploying the Application

Use this skill when:
- starting the app, in development or production
- something in `.env` needs to be set, and it is not obvious which variable
- the production build behaves differently from `deno task dev`
- publishing the schema to a database that is not the local container
- putting a second application (or a training copy) on the same machine
- deploying to Deno Deploy

The framework is a library: it never reads `Deno.env` by itself. The application does, in
one place — `configFromEnv()` inside `app/server.ts`. Every variable below is read there.

## Tasks

```bash
deno task dev              # backend + Vite together
deno task dev:server       # backend only (--watch)
deno task dev:front        # Vite only
deno task build:front      # production build into dist/
deno task startdb          # docker compose up -d (PostgreSQL)
deno task sql:registry     # regenerate app/_generated/** from manifest.json
deno task sql:assemble     # build the SQL package from the models' db/ files
deno task sql:publish      # publish it into the LOCAL database
deno task sql:deploy --yes # publish it into a REMOTE database
deno task skills:sync      # refresh .claude/skills from @altera/skills
```

After changing a model, almost always the same three:

```bash
deno task sql:registry && deno task sql:assemble && deno task sql:publish
```

## `.env`

One file, in the repository root — `docker-compose.yml` feeds from it too, so the database
password is written once. The template is `.env.example`; keep it current.

```
# Connection — libpq names, the ones psql, pg_dump and every managed database
# already understand. A provider that hands out a single string goes into
# DATABASE_URL: it is read when PGHOST and PGDATABASE are not set. The source is
# taken whole, never field by field.
# DATABASE_URL=postgres://user:pass@host:5432/db?sslmode=require
PGHOST=localhost
PGPORT=5432
PGDATABASE=myapp
PGUSER=myapp
PGPASSWORD=change-me
PGSSLMODE=            # empty → derived from the host: local plain, anything else `require`
DB_POOL_SIZE=10       # 1–3 on serverless: many isolates, each with its own pool

PORT=3000             # backend; vite.config.ts reads it too, to point the /api proxy here
VITE_PORT=5173        # Vite dev server; strictPort is on
VITE_DEV_URL=http://localhost:5173   # non-empty → views are served by Vite (dev mode)

BLOB_TOKEN_SECRET=change-me-in-production   # signs attachment links; the placeholder
                                            # refuses to start in production
AUTH_SESSION_TTL_HOURS=720
AUTH_COOKIE_SECURE=          # empty → on in production, off locally (http)
AUTH_COOKIE_NAME=myapp_session   # unique per machine — see "Several instances"

BOOTSTRAP_LOGIN=admin        # login + password together → an administrator is created
BOOTSTRAP_PASSWORD=          # on the first successful login
```

Everything else has a default. Two rules worth remembering:

- **`--env-file` does not override variables already exported in the shell.** `PGHOST` is a
  name people do export globally for their own `psql`, and then it quietly beats the
  project's `.env`. Where the app actually went is printed at startup:
  `✅ PostgreSQL <host>:<port>/<database> відповідає`. Start there when the data looks wrong.
- **TLS to the database follows the host** unless `PGSSLMODE` says otherwise. A managed
  database will not accept a plain connection, a local container does not offer TLS, and
  the only way to get this wrong is to forget the variable — so the default covers exactly
  that case. An explicit value, `disable` included, always wins; an unknown one fails at
  startup rather than silently opening an unencrypted connection.

## Development

```bash
deno task dev
```

Brings up the backend (`:3000`) and Vite (`:5173`). **Open the interface at the Vite
address.** While `VITE_DEV_URL` is non-empty, port 3000 serves only `/api`; the views come
from Vite as source modules. Opening `:3000` in this mode gives a page where no tab opens.

## Production

```bash
deno task build:front
```

Then **remove `VITE_DEV_URL` from `.env`** — otherwise the server keeps looking for views in
a Vite that is not running: the page loads and no tab ever opens. Run:

```bash
deno run --allow-net --allow-read --allow-env --env-file ./app/server.ts
```

The server now serves `dist/` itself.

**A production build is not the same code path as dev.** In dev the views arrive from Vite
as source modules; in production they are built chunks loaded by dynamic import, and the
shell creates each form from the chunk's exported `tagName`. Bugs that only exist in the
built output are invisible until then, so run the built app at least once before shipping.

## Publishing the schema

`sql:publish` refuses to run against anything but a local database, and against an
environment marked `production`/`prod`/`staging`. That guard is not about publishing — it
protects against the tools that **write test data** into whatever `.env` points at. It has
no bypass on purpose.

For a remote database there is a separate entry point:

```bash

From IgorAIvanov/altera03, MIT.

More from IgorAIvanov/altera03