Cloudline Press Scripts Overview

Cloudline Press uses a small set of shell and Python scripts to build, stage, and publish static websites using Listed.to as the content source. These scripts are intentionally simple, transparent, and auditable.

Goals

  • Static HTML output only
  • Atomic deployments
  • Reproducible timestamped releases
  • Manifest driven configuration
  • No runtime dependencies
  • Easy rollback

Directory Model

Each site follows this structure:

/var/www//
bin/
assets/
releases/
shared/
stage -> releases/
current -> releases/

Apache serves only the current directory.

Core Scripts

deploy.sh

Purpose:

Builds a new release and stages it safely without changing the live site.

Responsibilities:

  • Creates timestamped release directory
  • Initializes cache and metadata directories
  • Downloads and renders Listed content
  • Builds Markdown documentation
  • Installs shared banner support
  • Writes release metadata files
  • Updates stage symlink to new release

Important:

This script never changes the live site.

promote.sh

Purpose:

Switches the live site to the staged release.

Responsibilities:

  • Verifies stage points to a valid release
  • Updates current symlink to match stage

Properties:

Promotion is atomic and immediate.

Rollback is performed by repointing current to an older release.

listed_sync.py

Purpose:

Fetches content from Listed.to and converts it to static HTML.

Inputs:

  • Manifest URL
  • Listed page URLs defined in manifest

Responsibilities:

  • Downloads manifest
  • Builds navigation
  • Fetches page HTML
  • Extracts post content
  • Removes Listed UI elements
  • Caches fragments
  • Wraps content in site shell
  • Writes static pages

Important:

Site structure is controlled entirely by the manifest.

build_docs.py

Purpose:

Builds documentation pages from Markdown.

Inputs:

  • Markdown files located in assets/docs
  • Navigation generated during site build

Responsibilities:

  • Converts Markdown to HTML
  • Generates documentation pages
  • Creates automatic docs index
  • Applies site layout

Manifest Driven Design

Cloudline Press scripts do not hardcode page structure.

Instead:

Bootstrap manifest -> Content manifest -> Pages and navigation

This allows:

  • Multiple sites to reuse the same scripts
  • Content to change without modifying code
  • Reproducible rebuilds of old releases

Environment Configuration

Per site configuration lives in:

shared/env

Common values:

  • LISTEDMANIFESTURL
  • SITE_NAME
  • SITE_HOSTNAME
  • Asset overrides

Scripts explicitly load this file.

Deployment Flow

  1. Edit content on Listed
  2. Update manifest if required
  3. Run deploy.sh
  4. Verify staged release
  5. Run promote.sh

The live site is never modified until promotion.

Failure Behavior

If deploy fails:

  • stage is unchanged
  • current is unchanged
  • live site remains intact

If a bad release is promoted:

  • Repoint current to previous release
  • No rebuild required

Philosophy

Cloudline Press scripts are intentionally minimal.

Each script performs one clear function and exits.

The system favors reliability and transparency over abstraction.

Scripts