Installation

Tract Stack is free (as in kitten). If you’re able to provide an adequate home, it’s yours - made available under the source-available Functional Source License (only restriction is no re-selling Tract Stack as-a-service.)

Commercial use is encouraged. If you are an agency looking to build with Tract Stack, let’s chat.

If you’re up to the challenge we’ll provide you with everything required to install and self-host your own Tract Stack!

This is a technical guide

If you want Tract Stack as a service, visit Pricing for managed hosting and kitty “hoteling” options.

Quick install (for preview)

For non-production use you don’t even need Docker. It will work in dev mode just fine via a local-first Turso database.

pnpm create astro@latest my-tractstack-site --template AtRiskMedia/tractstack-starter/template --typescript strict --install --package-manager pnpm

cd my-tractstack-site
pnpm dev

Production install (recommended)

While Tract Stack can be run as a standalone in a Docker for production installs we offer this guide based on Debian Linux running Nginx with PHP 8.2 FPM, Docker.

For a production install you will need a Turso database url with read & write token. They offer a generous free tier which will be sufficient for most sites. Although we recommend at hobby tier for no cold starts and no database archival.

Production Install

Tract Stack should run on any VPS with 1-2GB ram. This guide and its scripts are based on Debian 12. If you port elsewhere, please let us know!

Create the t8k user

Tract Stack installs itself in the t8k user /home/t8k folder.

There are two steps involved. First, create the user. remember your password!

sudo adduser t8k
sudo usermod -aG sudo t8k

Next, become the t8k user and get the Tract Stack installer:

su - t8k
git clone https://github.com/AtRiskMedia/tractstack-installer

Prepare your environment

Log-in or become the t8k user.

Set your BASE_URL in ~/tractstack-installer/scripts/tractstack-install.sh

There is an optional USE_BACKUPS flag to enable. This depends on Backblack. Create a bucket and a ~/.env.b2 file:

B2_BUCKET_NAME=
B2_APPLICATION_KEY_ID=
B2_APPLICATION_KEY=

Note

Nginx will be configured for you by the install script. Two sub-domains are configured for each Tract Stack during the install process:

• hello.yourdomain.com will serve the frontend; this could be a CNAME pointing to yourdomain.com — if you update your primary domain, be sure to set the new domain in your Story Keep
• storykeep.hello.yourdomain.com will serve the backend services (e.g. to trigger a rebuild when required)

Run the install script

Use the tractstack-install.sh script to get a new instance of Tract Stack (e.g. 1 website). A new user account and /home/user folder will be generated through this process. (If you are running multiple websites, simply repeat the process with a different user name.)

cd ~/tractstack-installer/scripts
sudo ./tractstack-install.sh hello

Carefully decide upon a subdomain for this Tract Stack. It will also be used as username on Debian. It must be short and text only, no spaces. We’ll use hello as a default user name/sub-domain. Once your website is live, you can set-up the subdomains a CNAME records pointing to the primary domain.

Complete the installation

The install script will take 1-2 minutes.

All the instructions (and credentials) will be shown in the terminal. You will need to copy and paste these! Be sure to store them in a secure place afterwards.

Enter your Story Keep

Visit https://hello.yourdomain.com/storykeep/login?force=true (update with your domain; use the link provided in the terminal) and log-in with the account you made in the prior step.