altera-new-app

Files (1)

• SKILL.md

SKILL.md (first lines)

# Deploying a New Altera Application

This skill is for an **empty directory**: there is no application yet, and your job is to
take it from `jsr:@altera/create` to a login screen someone can actually log into.

Do not stop at the scaffold. It writes the files and prints six next steps — and those steps
are where installation actually breaks, quietly: a skipped `deno install` fails later rather
than where it was skipped; a leftover `VITE_DEV_URL` gives a blank page with no error; an
empty `BLOB_TOKEN_SECRET` does not matter until the app is marked production. Walk every
step and **verify the result**, not the fact that a command ran.

## 0. Preflight

Check before creating anything — redoing it costs more:

```bash
deno --version          # 2.9+ required
docker --version        # only if the database goes into a container
```

Ask the user unless already told: the **project name** (lowercase latin letters, digits,
`-`, `_`, first character a letter — it becomes the database name and goes into `sql.json`)
and **where PostgreSQL comes from** — a Docker container or an existing server. Do not
invent a name if the directory is not named to the pattern.

**The name must not repeat a neighbouring application's**, and that is not about tidiness:
the template derives `PGDATABASE`, `PGUSER` and `AUTH_COOKIE_NAME` from it. Two applications
with different names collide on nothing but the numeric ports; two with the same name collide
on all three at once — and that one is quiet, because the credentials match too, so
`sql:publish` publishes this schema into the neighbour's database and says nothing. What is
already on the machine:

```bash
docker ps -a --format "{{.Names}}\t{{.Ports}}"
```

Ports, all three at once (`deno` is here anyway, and this reads the same on Windows and POSIX):

```bash
deno eval --allow-net "for (const p of [3000,5173,5432]) { try { Deno.listen({port:p}).close(); console.log(p+' free') } catch { console.log(p+' BUSY') } }"
```

A busy port is not a silent failure — Vite has `strictPort`, `Deno.serve` throws `AddrInUse`,
Docker says `port is already allocated`. Looking early is about **order**, not about the
error: `PGPORT` has to be settled *before* `deno task startdb`, because the container creates
the database with whatever `.env` held at its first start, and editing the file afterwards
changes nothing (`deno task stopdb` and up again is the way back). `PORT` and `VITE_PORT` can
be changed at any time — `VITE_PORT` only together with `VITE_DEV_URL`.

## 1. Scaffold

From inside the empty directory:

```bash
deno run -A jsr:@altera/create .
```

The project name comes from the directory name. If it does not fit the pattern (spaces,
capitals, non-latin), pass one: `deno run -A jsr:@altera/create . --name myerp`.

The scaffold refuses to write into a non-empty directory. If it does, show the user what is
in there and ask; do not reach for `--force` on your own.

## 2. `.env`

```bash
cp .env.example .env
```

Then edit it — this is not a formality, three values have to change:

- **`PGPASSWORD`** — your own (the example says `change-me`). `docker-compose.yml` reads the
  same file, so the password is written once and cannot drift apart.
- **`BLOB_TOKEN_SECRET`** — it signs attachment links, and with the placeholder
  `change-me-in-production` a production server refuses to start at all. Generate one:

  ```bash
  deno eval "console.log(crypto.getRandomValues(new Uint8Array(32)).reduce((s,b)=>s+b.toString(16).padStart(2,'0'),''))"
  ```

- **`BOOTSTRAP_PASSWORD`** — set it if the administrator should be created automatically.
  Left empty, the login screen switches to "first run: create an administrator", where a
  human types both login and password. Both paths work; a password set here counts as
  temporary and must be changed on the first login.

**If another Altera application already lives on this machine**, these must differ: `PORT`,
`VITE_PORT` + `VITE_DEV_URL`, `PGDATABASE`, `BLOB_TOKEN_SECRET`, and — the least obvious one
— `AUTH_COOKIE_NAME`. Cookies do not distinguish ports: to a browser `localhost:3000` and
`localhost:3001` are the same host and one cookie jar, so with a shared name, logging into
the neighbouring app silently overwrites this session. The template already puts
`<project>_session` there, so with a distinct project name (step 0) the database, the role
and the cookie differ on their own — what is left to pick by hand is the ports and
`BLOB_TOKEN_SECRET`.

## 3. Database

```bash
deno task startdb
```

Brings up PostgreSQL in Docker with the credentials from `.env`. If step 0 showed 5432
busy, change `PGPORT` rather than fighting someone else's container — and change it before
this command, not after: the container takes `.env` as it is at first start and keeps it. With an existing PostgreSQL
this step is skipped: create the database and role (`create database <name> owner <role>`)
and put them into `.env`.

## 4. Dependencies — BEFORE the build

```bash
deno install
```

Not a formality. `deno.json` carries `"vendor": true`: the Vite preset and Tailwind read the
framework sources **from disk**, and the JSR cache is a flat list of hash-named files with
nothing to scan. Skip it and the build fails with
`Could not load .../vendor/jsr.io/@altera/client/...`.

If a framework release is less than a day old, Deno will not take it ("A newer matching
version was found, but it was newer than the specified minimum dependency date") — then

From IgorAIvanov/altera03, MIT.

More from IgorAIvanov/altera03