This guide covers everything you need to get Simple Website Framework up and running, from server requirements to your first page.
Server Requirements
Before you begin, make sure your server meets these requirements:
- PHP 7.4 or higher (PHP 8.x recommended)
- Apache with
mod_rewriteenabled - AllowOverride All set for your document root (required for
.htaccessto function)
The framework does not require a database, Composer, or any package manager. Everything it needs is bundled in the repository.
Installation
1. Get the files
The easiest way is the install package. Each release on the releases page has a swf-install-<version>.zip: the framework plus a clean starter site — a welcome home page, a menu, a 404 page, an archives page and three footer columns — with none of this documentation site's content in it. Unzip it into your web server's document root, or a subdirectory if you prefer, and make sure the hidden .htaccess file came along; some FTP clients hide files that start with a dot.
If you would rather have this documentation site as a starting point, or want to work from source, clone the repository instead:
git clone https://github.com/ScarylePoo/simple-website-framework.git
2. Copy and configure config.php
A config-example.php is provided in the config/ folder. Copy it to config.php and open it for editing:
cp config/config-example.php config/config.php
At minimum, set the following values before the site will work correctly:
$WebsiteURL— your domain name, without protocol (e.g.example.com)$SSL— set totrueif your site uses HTTPS$ForceWWW— set totrueto force thewww.prefix,falseto strip it
See the Configuration Reference for a full breakdown of every available option.
3. Verify Apache is configured correctly
The framework relies on .htaccess to route all clean URLs through index.php. If you are getting 404 errors on every page, mod_rewrite is likely not enabled or AllowOverride is not set to All.
On Ubuntu/Debian you can enable mod_rewrite with:
sudo a2enmod rewrite
sudo systemctl restart apache2
Not on Apache? The framework is written for Apache, and several protections live only in .htaccess files, which nginx, Caddy, IIS and any Apache host with AllowOverride None ignore. If you run one of those, recreate each of these in your server's own configuration, or the site will route correctly but leave files exposed that must never be served:
config/— deny everything.config.phpholds the editor's TOTP secret in plain text.backups/(or your$backupDir) — deny everything. Page history, deleted pages and whole-site zips.plugins/editor/lockouts.jsonandplugins/editor/totp-used.json— deny.*.draftanywhere underpages/— deny. Unpublished pages.- Every upload folder in
$uploadDirs— serve files, never execute them: no PHP handler for those paths. /edit→plugins/editor/index.php;/sitemap.xml→index.php?sitemap=1; everything else that is not a real file →index.php.- The security headers at the bottom of
.htaccess(X-Content-Type-Options,X-Frame-Options,Content-Security-Policy,Referrer-Policy).
An nginx server block covering all of it looks like this; adjust the PHP socket and the upload folders to match your own.
location ~ ^/(config|backups)(/|$) { return 404; }
location ~ ^/plugins/editor/.*\.json$ { return 404; }
location ~ \.draft$ { return 404; }
location ~ ^/(images|pages/images|pages/posts/images|videos)/.*\.php { return 404; } # your $uploadDirs; files there are never PHP
location = /edit { rewrite ^ /plugins/editor/index.php last; }
location = /edit/ { rewrite ^ /plugins/editor/index.php last; }
location = /sitemap.xml { rewrite ^ /index.php?sitemap=1 last; }
location / { try_files $uri $uri/ /index.php$is_args$args; }
location ~ \.php$ {
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
fastcgi_pass unix:/run/php/php-fpm.sock;
}
add_header X-Content-Type-Options nosniff always;
add_header X-Frame-Options SAMEORIGIN always;
add_header Content-Security-Policy "upgrade-insecure-requests; frame-ancestors 'self'; object-src 'none'; base-uri 'self'" always;
add_header Referrer-Policy strict-origin always;
4. Set file permissions
The web server needs read access to all files. If you intend to use HTML caching, the web server also needs write access to the root directory so it can create cache files:
chmod 755 /path/to/your/site
5. Visit your site
If everything is configured correctly, navigating to your domain should display the home page. If you see a blank page or errors, check your PHP error log.
Which version is a site running?
The version is recorded in required/version.php and shown in three places, none of them public: at the top of the editor next to the site title, on the meta overlay (?meta=yes), and from the command line with php plugins/editor/backup-cli.php version. A site cloned from the repository between releases reports the version it is heading towards.
It is deliberately not announced in a <meta name="generator"> tag or a public file. Scanners harvest those to match sites against known problems, and there is nothing to gain from making that easy.
Upgrading
Each release also has a swf-upgrade-<version>.zip. Unzip it over your existing site, replacing files when asked, and you are upgraded. It contains only framework code — index.php, required/, includes/, css/, plugins/, the two bundled themes and config/config-example.php — and never touches pages/, images/, config/config.php, robots.txt, your .htaccess or any theme of your own.
Three things to check afterwards, all spelled out in the UPGRADE.txt inside the zip:
- Compare
.htaccess.dist(the current reference copy, which Apache will never serve) with your.htaccess. If a release needs a new rewrite rule the release notes will say so, and you can copy the line across without losing your own redirects. - Look through
config/config-example.phpfor settings you do not yet have. New features are always off until you switch them on, so nothing changes until you do. - If you use HTML caching, delete any
cached-*.htmlfiles in the site root so pages are regenerated with the new code.
The bundled starter and skeleton themes are replaced by an upgrade. That is why the theme guide says to copy one to a new folder rather than editing it in place.
Development vs Production
The framework ships with caching disabled by default, which is correct for development. Before deploying to production, enable caching in config.php:
$enableHTMLCacheServe = true;
See the Caching page for full details.
Directory Structure
Here is a quick overview of what each folder does:
| Path | Purpose |
|---|---|
config/ |
Site configuration |
css/ |
Global CSS (normalize, base, flex grid) |
images/ |
Site-wide images (favicon, hero, defaults) |
includes/ |
Bundled JS libraries (jQuery) |
pages/ |
All page content as .html files |
pages/posts/ |
Blog post content |
pages/footer/ |
Footer column content |
plugins/ |
Plugin files and plugins.php loader |
required/ |
Core framework PHP files (do not edit) |
themes/ |
Theme folders |
themes/skeleton/ |
The default starter theme |
extras/ |
Optional tools not part of the core framework |
Next Steps
- Configuration Reference — every config variable explained
- Creating Pages — how to add content
- Theme System — how to customise the look and feel