Docker installation

Framework Cloud releases are published as a Docker image, ghcr.io/frameworktools/framework-cloud. A Compose file runs it as four containers:

app: the web server. FrankenPHP serves the app and gets an HTTPS certificate from Let's Encrypt for your domain.
worker: runs background jobs, such as creating GitHub repositories and sending email.
scaffolder: builds projects that people download as a zip. It runs fw, the framework R package, and framework-py, and only the app can reach it. Its image, ghcr.io/frameworktools/framework-scaffolder, has the same version tags as the app's.
postgres: the database.

Published notebooks, logs, certificates, and the database are kept in Docker volumes, so they survive restarts and upgrades.

Requirements

Docker with the Compose plugin
A domain whose DNS points at the machine, with ports 80 and 443 open

For a single-user server on your own computer, see Local installation.

Installation

Make a folder for the server and download the Compose file and the settings template:

mkdir framework-cloud && cd framework-cloud
curl -fsSLO https://raw.githubusercontent.com/frameworktools/framework-cloud/main/docker/selfhost/compose.yml
curl -fsSL https://raw.githubusercontent.com/frameworktools/framework-cloud/main/docker/selfhost/.env.example -o .env

Generate an application key:

docker run --rm ghcr.io/frameworktools/framework-cloud php artisan key:generate --show

Put the printed key in .env as APP_KEY. Keep a copy with your backups, because values saved on the Server setup page are encrypted with it.

Then set these in .env:

APP_URL: the address people use, such as https://framework.example.edu
SERVER_NAME: the domain alone, such as framework.example.edu
FW_ADMIN_EMAIL: your email address
DB_PASSWORD: a long random string, such as the output of openssl rand -hex 24
FRAMEWORK_CLOUD_VERSION: optional, a release such as 1.2.0. Without it, the server uses the newest release.

Start the server:

docker compose up -d

The first start downloads the images, creates the database tables, and adds the built-in blueprints and your admin account. Check progress with docker compose ps and docker compose logs -f app.

Reverse proxy configuration

If another web server already handles HTTPS on the machine, such as nginx, Traefik, or Nginx Proxy Manager, let it pass requests to Framework Cloud over plain HTTP. Set these in .env:

SERVER_NAME=:80
HTTP_PORT=8080
TRUSTED_PROXIES=*

Point the proxy at port 8080. TRUSTED_PROXIES lets the app read the proxy's forwarded host and scheme, so it builds https:// links. Use * only when nothing but the proxy can reach the port. Otherwise list the proxy's address, such as TRUSTED_PROXIES=192.168.1.10.

Email isn't set up yet, so print a sign-in link on the server:

docker compose exec app php artisan fw:login-link you@example.edu

Open the link. As an admin you see Server setup in the sidebar. Continue with Server setup.

You can also set a password and sign in with it:

docker compose exec app php artisan fw:password you@example.edu

Account registration

By default anyone who can reach the server can create an account. To stop new sign-ups, set FW_REGISTRATION=closed and restart. Admins can still create accounts:

docker compose exec app php artisan fw:login-link someone@example.edu --create

Next steps

Server setup: email, GitHub, and storage
Maintenance: upgrades and backups
Configuration reference

Custom Docker images

To run code that isn't in a release, such as your own changes, build the image from a clone of the repository:

git clone https://github.com/frameworktools/framework-cloud.git
cd framework-cloud/docker/selfhost
cp .env.example .env    # then fill it in as above
docker compose -f compose.yml -f compose.build.yml up -d --build

Edit this page on GitHub