Skip to content

Getting Started with Statamic

Statamic is a powerful flat-file CMS that’s a great fit for the Webslice Serverless platform. We even use it for our own website! This guide takes you from a working Statamic site to a live deployment on Webslice.

It assumes you already have a Statamic site running locally. If you’re starting fresh, the official Statamic documentation will get you set up first. Once your site is live, head to Optimizing Statamic to tune it for performance and cost.

How Deploys Work

Before the steps, it helps to know how a deploy works on Webslice, because it shapes a few choices below.

Webslice deploys your site from a git repository. You connect a repository once, and from then on a push to your chosen branch creates a new deploy. Git deploys support two strategies:

  • Versioned (the default) - each deploy is atomic: a fresh, complete copy of your site. That makes rollbacks instant, but it also means anything not tracked in git won’t carry over to the next deploy unless you put it in persistent storage.
  • Live - a single directory that’s synced incrementally, so untracked files left on the server persist between deploys.

Most sites start on versioned, and that’s what this guide assumes.

Webslice is also a dynamic environment, so you can still log into the Statamic Control Panel and make quick edits on the live site. Just remember that with versioned deploys those edits live only on the current copy. Commit and push the same change to git, or it’s lost on the next deploy.

Get Your Site Into Git

Since we deploy from a git repository, your site needs to live in one.

  • Existing site - if it’s already in a git repository, you’re good to go.
  • New repository - create a repository on your preferred git host (GitHub, GitLab or Bitbucket) and add your site files. Keep everything inside a single top level folder, named whatever you like, for example mysite/.

Don’t commit the vendor folder that Composer creates. Add it to your .gitignore and install dependencies during the deploy with a build script instead, which we’ll set up next.

The Build Script

Your build script runs during the deploy and prepares the application before it goes live. For Statamic that means installing Composer dependencies and generating an application key.

Create a .webslice/build.sh file in your repository:

.webslice/build.sh
#!/bin/bash
set -ex


cp .env.example .env
composer install --no-interaction --no-dev --prefer-dist --optimize-autoloader
php artisan key:generate

The set -ex line does two things: -e stops the script at the first command that fails, so a broken build never goes live, and -x echoes each command as it runs, which is what makes the deploy log readable when you need to work out what went wrong.

Make it executable before committing:

Terminal window
chmod +x .webslice/build.sh

See Build & Release Scripts for more on how build scripts work.

Create the Site

In the Webslice Console, select the project you want the site under and add a new website:

  1. Press + Add and fill in the details.

  2. Pick a PHP version that matches your site. Statamic 6 needs PHP 8.3 or newer, and Statamic 5 needs PHP 8.1 or newer - see the Statamic requirements if you’re unsure.

  3. Set the Document Root to your site’s public directory. Statamic is built on Laravel, so the web root is the public folder inside your top level folder, for example mysite/public.

  4. Once the site is created, open Settings » Build & Deploy and set the build script path to .webslice/build.sh. You can also set this from a .webslice/settings.toml file in your repository instead.

Environment Variables

Your build script copies .env.example to .env, so anything environment-specific should come from the console instead. In the Env Vars section of your website, add:

Terminal window
APP_ENV=production
APP_DEBUG=false

Without these your site runs with the defaults from .env.example, which usually means debug mode is left on. Debug pages can leak configuration details, so make sure it’s off in production.

This is also the place for anything secret or environment-specific: API keys, database credentials, and your APP_KEY. Setting APP_KEY here keeps it stable across deploys, so sessions and encrypted data survive each release - it takes precedence over the fresh key the build script generates. You can generate one locally with php artisan key:generate --show.

Connect Your Repository

Webslice needs access to your repository so it can pull your code on each deploy. There are two ways to set this up:

  • Git connection (recommended) - from the website’s Deploys or Settings page, connect your GitHub, GitLab or Bitbucket account, then pick the repository and the branch to deploy from. Access and webhooks are configured for you, so every push to that branch creates a deploy.
  • Manual deploy keys - for self-hosted providers, or if you’d rather manage access yourself, add an SSH deploy key and webhook to the repository by hand.

The Git Deploys guide walks through both in detail, along with how to choose whether deploys trigger automatically or wait for you to release them manually.

Add a Database (If You Need One)

Statamic is flat file by default and many sites don’t need a database at all. If yours does, for users, database-backed forms, or an addon that requires it, add one from the Databases tab and make sure its region matches your website. Store the credentials as environment variables rather than committing them.

Deploy and Go Live

With your repository connected, push to your deploy branch (or trigger the deploy manually from the Deploys tab). Your build script runs, and once it finishes the site comes Online. You can then visit it on its onwebslice.com address, or point your own domain at it from the Domains tab.

Your Statamic site is now live. Next, see Optimizing Statamic to enable static caching, persist uploads and caches between deploys, and warm the cache after each release.