Install Overview

This page explains how to install the Cloudline Press reference implementation on a fresh host.

Cloudline Press is a manifest-driven static publishing system. The installer’s job is to create a predictable directory layout under /var/www, fetch the current scripts and docs from Listed, and set correct ownership and permissions.

It is not a package manager and it does not attempt to manage Apache for you unless you explicitly choose to.

What you get after install

A site root like this:

/var/www/cloudlinepress/
bin/ executable scripts (deploy, promote, builders)
assets/ static inputs (docs, errors, css, images)
releases/ timestamped builds
shared/ site env + banner controls
logs/ site logs (optional)
stage -> releases/
current -> releases/

Apache should point DocumentRoot at:

/var/www/cloudlinepress/current/public

The two manifests

There are two concepts that often get conflated:

1) Bootstrap manifest
This is what the installer reads first. It tells the installer where to find everything else, especially the content manifest that lists scripts and docs.

2) Site manifest
This is what listed_sync.py uses at build time. It defines site navigation and the pages to pull from Listed.

Install uses the bootstrap manifest.
Build uses the site manifest.

Default bootstrap manifest

The installer should have a default bootstrap manifest URL baked in, so a new system can be installed with one command.

Default:

https://listed.to/p/u2Ba9oqF2Z

The bootstrap manifest is expected to be JSON inside the first pre/code block on that Listed page.

What the installer does

At a high level:

  • Creates /var/www/cloudlinepress if missing
  • Creates bin, assets, releases, shared
  • Writes shared/env (site-local configuration)
  • Downloads the content manifest URL from the bootstrap manifest
  • Downloads scripts from the content manifest into bin
  • Downloads docs from the content manifest into assets/docs
  • Installs minimal assets (css, icons, lizzie images, error pages)
  • Sets ownership and permissions for a web-served directory tree
  • Optionally runs deploy.sh once to create an initial release

The installer should be safe to re-run.
Re-running should refresh scripts and docs but should not delete releases.

shared/env (site-local configuration)

The installer should create or update this file:

/var/www/cloudlinepress/shared/env

Typical contents:

SITENAME="Cloudline Press"
SITEHOSTNAME="cloudlinepress.amongthe.cloud"
LISTEDMANIFESTURL="PUTSITEMANIFESTURLHERE"

LIZZIEDARKPNG="/assets/lizzietransb.png"
LIZZIELIGHTPNG="/assets/lizzietransw.png"

LISTEDMANIFESTURL is the site manifest used by listed_sync.py during deploy.

This is the single most important value for preventing accidental cross-site builds.

Permissions model

Recommended ownership:

  • /var/www/cloudlinepress owned by root or www-data depending on your policy
  • bin scripts readable by root and executable by you
  • releases and public output readable by www-data
  • assets readable by www-data

A safe baseline:

  • Directories: 0755
  • Files: 0644
  • Executable scripts in bin: 0755

Avoid making the whole tree group-writable unless you have a reason.

First build and promotion

After install, the standard workflow is:

cd /var/www/cloudlinepress/bin
./deploy.sh
./promote.sh

deploy.sh creates a new release and updates stage.
promote.sh switches current to the staged release.

Verify

After promotion:

  • current should be a symlink to a release

    ls -l /var/www/cloudlinepress/current

  • Stage should be a symlink to the same or newer release

    ls -l /var/www/cloudlinepress/stage

  • The web root should exist

    ls -al /var/www/cloudlinepress/current/public

  • The site should respond

    curl -I https://cloudlinepress.amongthe.cloud/

Common failure cases

Wrong site content showing up
This almost always means LISTEDMANIFESTURL points to the wrong site manifest, or you are using a bootstrap/content manifest in place of the site manifest.

JSON parse errors during deploy
If a section intro page starts with a code block that is not JSON, and your builder tries to interpret it as JSON, adjust the builder to test JSON quietly or move the code block lower in the page.

Missing errors/*.html
If assets/errors contains no html files, deploy scripts that stamp placeholders may fail unless they handle empty globs safely.

Upgrade model

To update scripts:

  • Update the script URLs in the content manifest
  • Re-run the installer or a script-sync step
  • Run deploy.sh again

To update content:

  • Update Listed pages
  • Run deploy.sh, then promote.sh

Notes

Cloudline Press is built around the idea that all inputs are inspectable and all output is static. The install step is intentionally small so you can understand exactly what it changes on the machine.

Install