ForgeCrowdBookWe don't sell the fish – we give you the rod.

Without AI

This book is about building a website by describing it. But ForgeCMS does not need an AI. Everything the AI did in these chapters, you can do yourself, and some readers want to know how it works underneath. This chapter is the map for them. It is a little more technical than the rest; skip it if you are happy asking.

Goal

By the end of this chapter you will know:

  • how to build and run ForgeCMS by hand,
  • how a site is laid out on disk,
  • the commands that tell you what ForgeCMS can do.

What you need

  • A computer or server with Linux or macOS. (Windows is not supported.)
  • Git.
  • cmake and a C++ compiler, to build ForgeCMS. (ForgeCMS is written in SMS, a small language of its own, and compiled to one binary. You do not need to know SMS to run it, and there is nothing else to install: no Go, no PHP, no database.)
  • On the server later: curl and sendmail (Postfix) for the modules that send mail.

Build it

git clone https://codeberg.org/CrowdWare/ForgeCMS.git
cd ForgeCMS
./run.sh sms-cms

./run.sh sms-cms builds ./forgecms-sms, one binary of about 6 MB. The first run also builds the SMS runtime it needs, which takes a few minutes. For a server with an older Linux, ./run.sh sms-cms-linux builds a binary that runs there too (it needs the compiler zig).

(Earlier versions of ForgeCMS were written in Go. That version is kept in the repository under the tag go-final.)

A site on disk

ForgeCMS looks for its sites in a folder sites/, next to where you start it, one subfolder per domain. The smallest site is a subfolder with two files:

myserver/
    forgecms-sms
    sites/
        localhost/
            app.sml
            index.sml

sites/localhost/app.sml:

App {
    name: "My Site"
    lang: "en"
    Site { local_path: "sites/localhost" }
    Routing {
        Route { path: "/" page: "index.sml" }
    }
}

sites/localhost/index.sml:

Page {
    title: "Hello"
    Heading { level: 1 text: "Hello" }
    Text { value: "My first ForgeCMS page." }
}

Run it:

cd myserver
./forgecms-sms --port 8080

Open http://localhost:8080. That is a ForgeCMS site.

Site { local_path: "sites/localhost" } means: pages and texts come from this folder (the path is relative to where you start ForgeCMS). For a site whose content is on Codeberg, Site names the repository instead (host, user, repo, branch, optionally path for a subfolder), as in chapter 5.

A real site adds, next to app.sml:

File or folder For
theme.sml colours and fonts (chapter 7)
static/ pictures, style.css, favicon
templates/ the HTML frame, only if you want your own; otherwise the built-in one is used
license.sml licence keys for the modules (chapter 16)
data/ what modules store: orders, subscribers, plugin records. This folder lies next to sites/, not inside the site; --data sets it

Asking ForgeCMS what it can do

ForgeCMS describes itself in a few files in the repository. These are the files the AI reads, and you can too:

File Tells you
sms/data/elements.sml every page element with its properties
sms/data/modules.sml every module: what it does, its app.sml block, an example, its price
sms/data/default-theme.sml the built-in design values
sms/plugins/SPEC.md the plugin API (chapter 17)

There is more: README.md for people, AI.md for the technical details, forge-cms-spec.md for the exact behaviour of every module.

Several sites on one server

One ForgeCMS process serves many sites: it looks for sites/<domain>/app.sml and serves each domain from its folder. My own server runs several sites this way, with one forgecms-sms process and one Caddy in front.

Running it for real

On a server, three more pieces:

  1. A service, so ForgeCMS starts on boot and restarts if it stops. With systemd, a unit that runs forgecms-sms --port 8080 in the folder that holds sites/ is enough. The deploy.sh of the sites repository writes one; or ask the AI.

  2. Caddy in front, for HTTPS. A Caddyfile with one block per domain is enough:

    mybakery.com, www.mybakery.com {
        reverse_proxy localhost:8080
    }
    

    Caddy gets and renews the certificates by itself.

  3. Mail, if you use modules that send mail: an SMTP { } block in app.sml pointing to a mail server, or a local Postfix (ForgeCMS sends through sendmail) with SPF and DKIM for your domain.

Updating

cd ForgeCMS
git pull
./run.sh sms-cms
systemctl restart forgecms-sms

(Replace the service name with the one you chose.)

What you learned

  • ./run.sh sms-cms builds ForgeCMS as one binary, forgecms-sms; plugins are part of it.
  • A site is a folder sites/<domain>/ with an app.sml, pages and texts; ./forgecms-sms --port 8080 serves all sites in sites/.
  • sms/data/elements.sml, sms/data/modules.sml, sms/plugins/SPEC.md and the documents in the repository describe everything.
  • On a server: a systemd service, Caddy for HTTPS, and mail for the modules that need it.

This is the end of the book. You know where everything is, what each part does, and how to ask for what you need. The rest is your website.