# Trap 6. The person names an address — everything else you already know

If the person says "deploy my application to `contracts.example.com`", it means the site has
**already been created** and configured for them: subdomain, user, directory, database,
certificate, route. They are not obliged to tell you anything more, and there is nothing to ask
them.

Everything else follows from the address itself. This file is about how.

---

## What the address tells you

**The domain can be anything.** Do not count on a particular name: sites live under different
domains and all of them point at the same server. Only the **first label of the address** — the
part before the first dot — matters. That label is the site's name.

Say the person named `contracts.example.com`. The site name is `contracts`, and everything
follows from it:

| What | Where |
|---|---|
| SSH access | `ssh contracts@contracts.example.com` (port 22, key only) — the host is the whole address, the username is the first label |
| Application code | `/srv/contracts/app` |
| Start command | `/srv/contracts/start.sh` — you write it |
| Port | inside `start.sh`, the `export PORT=…` line |
| Your own variables | `/srv/contracts/.env` |
| Site secrets | `/etc/contracts.env` — holds `DATABASE_URL`, and **overrides** the previous file |
| Control | `sudo contractsctl start\|stop\|restart\|status\|logs [lines]` |
| Public address | `https://contracts.example.com` — the certificate already exists |

The username, the database name and the first label of the address are one and the same word.
Remember that rule and there is nothing left to ask. Parsing the address is enough:

```bash
FQDN=contracts.example.com
NAME=${FQDN%%.*}          # contracts — user, directory, database, command prefix
```

---

## First check that the address leads to the right server

The domain can be anything — the person may have bought it themselves. The server is the same
one regardless. So before doing any work, confirm the address really points at it:

```bash
FQDN=bma.example.org
dig +short "$FQDN"                      # the address the person named
dig +short vibe.postplatforms.com       # the reference: the server these instructions came from
```

Both must give **the same IP**. The reference is taken from live DNS rather than from a number
hard-coded in this text, so the check does not go stale if the server moves.

The decisive check is still the login:

```bash
ssh -o BatchMode=yes -o ConnectTimeout=10 "${FQDN%%.*}@$FQDN" 'echo ok'
```

**If the IPs do not match** — stop, deploy nothing. Tell the person in plain words:

> The address `bma.example.org` currently points somewhere other than the server where the
> application is supposed to live. That is a DNS setting, and only the server's owner can fix
> it. Message them in Meshenger — Egor (`@ad0c3d86-c042-59ca-b65f-5454cdaadcb1`) — and pass on
> this address plus what I see: `dig +short bma.example.org` returns &lt;what it returned&gt;, and it
> should match `dig +short vibe.postplatforms.com`.

The same applies if the name does not resolve at all: the A record has not been created yet.

**If the IPs match but SSH is refused** — that is not DNS, it is access; see the next section.

---

## The only thing you might not have

Access. Login is by key only, and your public key has to be in
`/srv/<name>/.ssh/authorized_keys`. Only the server's owner can put it there.

So check for access first:

```bash
ssh -o BatchMode=yes contracts@contracts.example.com 'echo ok'
```

It answered `ok` — carry on, ask nothing. It refused — ask the person **once** to pass your
public key to whoever gave them the address:

```bash
cat ~/.ssh/id_ed25519.pub     # if there is no key: ssh-keygen -t ed25519 -C "deploy" -N ""
```

Only the `.pub` is passed on. The file without `.pub` is never shown to anyone.

---

## The boundary

The server is shared: other people's applications and other people's data live next door.

- Everything you need is **inside your own user** and in the single `<name>ctl` command.
- Root is not needed. If it seems to be, you are doing the wrong thing.
- Do not touch Caddy, systemd, `/etc/postplatforms.conf`, or other directories in `/srv`.
- Do not create sites yourself: provisioning new subdomains is the server owner's job.

The DNS token stored on the server controls **every** domain in the account. Do not ask for it,
do not read it, do not mention it.

---

## The order of work

### 1. Find the port and see what is already there

```bash
ssh contracts@contracts.example.com 'grep -m1 "^export PORT=" start.sh; ls -la app | head'
```

If there is already something in `app`, do not overwrite it silently. Show the person what is
there and ask whether you are replacing or updating.

### 2. Put the code up

`git clone` inside the directory, `rsync` from outside, or `scp` — nothing special:

```bash
rsync -az --delete --exclude .git --exclude node_modules \
  ./ contracts@contracts.example.com:/srv/contracts/app/
```

The directory must not end up containing a `.env` with secrets, private keys, or
`w3ds-deployment-key.json`. Secrets come from `/etc/<name>.env`, not from the repository.

### 3. Write the start command

The stock `start.sh` deliberately exits with an error until it is replaced, so that nobody has
to guess "why won't it come up". Replace the body:

```bash
#!/usr/bin/env bash
set -euo pipefail

export NODE_ENV=production
export HOSTNAME=127.0.0.1
export PORT=3006            # the one already in the file — do not change it

cd "$(dirname "$0")/app"
exec node server.js         # ← your real command
```

**Listen on `127.0.0.1:$PORT` only.** Caddy serves the outside world; a port opened on
`0.0.0.0` is reachable by the machine's other tenants, bypassing the proxy.

### 4. Migrations, if any

`DATABASE_URL` lives in `/etc/<name>.env`. systemd injects it into the application, but in an
interactive session you have to source the file explicitly — your user is allowed to read it:

```bash
ssh contracts@contracts.example.com \
  'set -a; . /etc/contracts.env; set +a; cd app && npm run migrate'
```

### 5. Start it and make sure

```bash
ssh contracts@contracts.example.com 'sudo contractsctl restart && sudo contractsctl logs 200'
curl -s -o /dev/null -w "%{http_code}\n" https://contracts.example.com
```

Expect `200`. A `502` **before** the first successful start is normal. A `502` **after** means
the application crashed or is listening on the wrong address — read `logs`.

### 6. Move eID sign-in to the new address

The tunnel from trap 3 is no longer needed and should be switched off. The base URL becomes
`https://<the address the person named>`, and `redirect=` in the wallet offer is built from it.

While you are here, put that same address into the repository's **Application URL** field on the
**W3DS** tab — the PPA certificate checklist requires it. That is Part B of
`traps/02-gitw3-registration.md`, and now is when it becomes possible.

**Check by the person:** they open the new address **on their phone** and sign in with eID both
ways, as in trap 4. Until that is done, the deployment is not finished.

---

## What breaks the first time

| Symptom | Cause |
|---|---|
| `Permission denied (publickey)` | your key is not in `authorized_keys` — the one thing worth asking the person for |
| `502` after starting | you are listening on `0.0.0.0` or the wrong port instead of `127.0.0.1:$PORT` |
| the application dies immediately | `start.sh` is still the stock stub with `exit 1` |
| no `DATABASE_URL` | in an interactive session it has to be sourced from `/etc/<name>.env` explicitly |
| "I need root" | almost always: you have stepped outside your own user |
| eID sign-in broke after the move | the base URL is still the tunnel's |

---

## If the application is no longer needed

Tearing a site down is also the server owner's job; they have the inverse command, which prints
a plan, dumps the database and archives the directory before deleting anything. Tell the person
the site is worth releasing rather than abandoning.

---

*This section was written from the deployment system's code and sent to its authors for review.
If the output of a command on the server disagrees with this text, believe the server and say so
out loud.*
