Recipes: static sites

Ready-to-copy examples, from a brand-new site to automatic deploys. Each recipe has the command, what it prints, and a prompt to ask your agent for the same thing. The output below is real, taken from rapadura in production.

Before you start: the CLI is installed and rapadura login is done (Getting started). The examples use a site called php-sobral-2026; use your own name.

A new site in plain HTML

A folder with index.html at its root is already a site. Nothing to install, nothing to configure.

site/
  index.html
  programacao.html
  palestrantes/index.html
  404.html
  style.css
  img/palco.png

shell

rapadura publish ./site --site php-sobral-2026 --create --title "PHP Sobral 2026"

output

Packed 7 files (0.0 MB), uploading...
Created php-sobral-2026.rapadura.net
PHP Sobral 2026 is live at https://php-sobral-2026.rapadura.net (version 1).
  live: https://php-sobral-2026.rapadura.net
  version: 1 (7 files, 0.0 MB)
  version url: https://php-sobral-2026--v1.rapadura.net
  next: Open https://php-sobral-2026.rapadura.net to confirm the result; the first HTTPS visit may take a few seconds while the certificate is issued.
  next: Publish again to the same site to update it. Roll back any time with: rapadura rollback php-sobral-2026.rapadura.net 1
  next: Version 1 keeps its own address for as long as it is retained: https://php-sobral-2026--v1.rapadura.net

What the server does with that folder:

programacao.html answers at /programacao and at /programacao.html.
palestrantes/index.html answers at /palestrantes/ (and /palestrantes redirects there).
404.html becomes the "not found" page.
Images, CSS and JS are cached for a week. When you change one, change its name too (style.v2.css) if everyone must see it right away.

Ask your agent

Build a one-page hotsite for PHP Sobral 2026 (November 14, Sobral, Ceará) in ./site: intro, schedule, speakers and a sign-up button pointing at https://www.sympla.com.br/. Plain HTML and CSS, no frameworks. Then publish it on rapadura as php-sobral-2026 and tell me the address and the version.

With a site generator

Run the build and publish the output directory, never the project root.

tool	build	publish
Astro	`npm run build`	`./dist`
Vite (React, Vue, Svelte)	`npm run build`	`./dist`
Hugo	`hugo`	`./public`
Eleventy	`npx @11ty/eleventy`	`./_site`
Jekyll	`bundle exec jekyll build`	`./_site`
Next.js with `output: 'export'`	`npm run build`	`./out`

shell

npm run build && rapadura publish ./dist --site php-sobral-2026 --create

The site is served at the root of its hostname. If the generator asks for the final address (site in Astro, baseURL in Hugo, url in Jekyll), use https://php-sobral-2026.rapadura.net/ and leave base empty.

The usual stumble. Publishing the repository root drags along .env, keys or .php files, and rapadura refuses all of it at once, with the list:

output

error (archive_forbidden_file): 2 file(s) cannot be published:
  .env (credential-like file)
  contato.php (server-side code is never executed on the static lane)
hint: publish a generated output directory that holds only the public files

There is no way to force it. Publish the output directory or remove the files. .git, node_modules, vendor and .cache are skipped silently.

Ask your agent

Build this project and publish the output directory on rapadura as php-sobral-2026, creating the site if it does not exist yet. If rapadura refuses any file, show me the list and do not try to work around it.

Update, check, roll back

Publishing again to the same site makes a new version. -m stores a note.

shell

rapadura publish ./site --site php-sobral-2026 -m "registration open"
rapadura versions php-sobral-2026

output

VERSION  STATUS    FILES  SIZE   BY    WHEN              URL                                       MESSAGE
v2       live      7      0.0MB  rtio  2026-10-13 11:54  https://php-sobral-2026--v2.rapadura.net  registration open
v1       archived  7      0.0MB  rtio  2026-10-13 11:54  https://php-sobral-2026--v1.rapadura.net

Every version keeps its own address (php-sobral-2026--v1.rapadura.net) while it is retained: compare two versions side by side, or show someone a version that is no longer live (after a rollback, say).

Something broke? Go back to the previous version. Nothing is rebuilt: the switch is instant and atomic.

shell

rapadura rollback php-sobral-2026 1
rapadura sites show php-sobral-2026

output

php-sobral-2026.rapadura.net
  status: live
  version: v1
  owner: rtio
  live: https://php-sobral-2026.rapadura.net
  created: 2026-10-13 11:54
  title: PHP Sobral 2026

To move forward again, run rollback with the newer version's number. The last 20 versions are kept.

Ask your agent

The last publish of php-sobral-2026 broke the home page. Look at its versions on rapadura, roll back to the previous one and confirm by opening the site.

Redirects and the 404 page

A _redirects file at the site root, one rule per line: source target [301|302]. Exact paths only, no wildcards.

/inscricoes   https://www.sympla.com.br/   302
/2025/        /                            301

shell

curl -sI https://php-sobral-2026.rapadura.net/inscricoes | grep -iE '^(HTTP|location)'

output

HTTP/2 302
location: https://www.sympla.com.br/

_redirects itself is never served, and an invalid line refuses the publish saying which one. For the error page, a 404.html at the root is enough.

Take a site offline and bring it back

shell

rapadura sites delete php-sobral-2026 --yes

output

php-sobral-2026.rapadura.net is offline. Files are kept for a while; bring it back with: rapadura sites restore php-sobral-2026.rapadura.net

Visitors get 410 Gone and the name stays reserved for you. Changed your mind?

shell

rapadura sites restore php-sobral-2026

output

php-sobral-2026.rapadura.net is back online at https://php-sobral-2026.rapadura.net (status live, version v1).

The site comes back with the version that was live and all its history.

Your own domain

A static hotsite can also answer at a domain the event owns, like www.phpsobral.com.br. Ask for it; the request waits for the owner's approval and tells you which DNS record to create meanwhile:

shell

rapadura domain add php-sobral-2026 www.phpsobral.com.br --reason "event domain, registered by the organizers"

output

Request #2 (domain.add www.phpsobral.com.br → php-sobral-2026.rapadura.net) is waiting for the owner's approval.
  next: Point www.phpsobral.com.br at 168.196.105.251 (A record) — the certificate is issued automatically on first visit after approval.
  next: Nothing changes until the owner approves; the site keeps answering at https://php-sobral-2026.rapadura.net.
  next: The owner decides at https://agents.rapadura.net/approvals or with: rapadura approvals approve 2
  next: Undecided, the request expires on 2026-10-20. Follow it with: rapadura approvals

Follow it with rapadura approvals; once approved, rapadura domain list php-sobral-2026 shows the domain. rapadura domain remove detaches it with no approval. The rules (which names are refused, WordPress sites) are in Rules and limits.

Ask your agent

Ask rapadura to map www.phpsobral.com.br to the php-sobral-2026 hotsite, tell me exactly which DNS record I must create and how I can follow the request.

On the phpcomrapadura.org domain

The same site can live under phpcomrapadura.org. Use the full name:

shell

rapadura publish ./site --site php-sobral-2026.phpcomrapadura.org --create

or --site php-sobral-2026 --zone phpcomrapadura.org. They are two independent sites, each with its own versions. rapadura zones lists the available domains and the limits.

Watch the traffic

shell

rapadura logs php-sobral-2026 -n 20

Each line is JSON with time, path, status, size and browser. With jq, the most viewed pages among the last 2000 requests:

shell

rapadura --json logs php-sobral-2026 -n 2000 \
  | jq -r '.lines[] | fromjson | .uri' | sort | uniq -c | sort -rn | head

Ask your agent

Look at the last 2000 requests to php-sobral-2026 on rapadura and tell me the most visited pages, how many 404s there were and for which paths.

Publish on every push (GitHub Actions)

Ask the administrator for a token just for CI, one per repository (they mint it with rapadura admin bootstrap-token, see Administration). Save it as the RAPADURA_TOKEN secret in the repository. Never reuse your computer's token and never put a token in a project file.

YAML

# .github/workflows/publish.yml
name: publish
on:
  push:
    branches: [main]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci && npm run build
      - name: Install the rapadura CLI
        run: |
          curl -fsSL https://agents.rapadura.net/install.sh | sh
          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
      - name: Publish
        run: rapadura publish ./dist --site php-sobral-2026 -m "commit ${GITHUB_SHA::7}"
        env:
          RAPADURA_TOKEN: ${{ secrets.RAPADURA_TOKEN }}

If the publish fails, the step fails and the previous version stays live.

More prompts to try

Ask your agent

List my hotsites on rapadura with each one's version and tell me which have not been published to in more than 30 days.

Ask your agent

Update only the schedule of php-sobral-2026 from programacao.csv (columns: time, title, speaker). Keep the rest of the site as is, publish with the message "schedule updated" and send me the address.

Ask your agent

Copy php-sobral-2026 to php-sobral-2026.phpcomrapadura.org: publish the same folder there and check that both URLs open.