Static Site Generators (SSGs) runtime

Overview

Static is a flexible, light and simple runtime dedicated to static sites generators (SSG), designed for minimum configuration effort with Auto-build feature. Pico instances are available, it allows users to put services in front of it, such as Redirection.io or Varnish.

Create your Static application

To create a new Static application, use the Clever Cloud Console or Clever Tools:

clever create --type static

• Learn more about Clever Tools
• Learn more about Clever Cloud application deployment

Configure your Static application

Mandatory needs

Static runtime only requires a working web application, with an index.htm or index.html file. If you need to serve files from a specific directory, set the CC_WEBROOT environment variable, relative to the root of your project (for example /public, default is /).

• Learn more about environment variables on Clever Cloud

Build phase

During the build phase, Clever Cloud will run the CC_BUILD_COMMAND if provided. You can use it to install dependencies, build your static website, or any other task you need to perform before running your application. If no CC_BUILD_COMMAND is provided, Clever Cloud will try to detect your Static Site Generator (SSG), build and deploy your website automatically.

• Learn more about Deployment hooks
• Learn more about Static Site Generators (SSGs) Auto-build

Optimized build cache

When auto-build activates, or if you define CC_WEBROOT, the build cache contains only some configuration files and the served directory to optimize size, reduce archive time. When neither option applies, the system caches the entire application root directory instead.

To override this behavior, set the CC_OVERRIDE_BUILDCACHE environment variable with a colon-separated list of directories and files, relative to the application root. For example: CC_OVERRIDE_BUILDCACHE=myScript.sh:/myBuildDir.

Supported web servers

By default, Static Web Server (SWS) 2.40.1 serves your website. If a valid Caddyfile is present at the root of your project, it will be used with Caddy 2.10.2 and the caddy run command, you can also set its location with CC_STATIC_CADDYFILE (Default is ./Caddyfile).

You can force the use of Caddy by setting the CC_STATIC_SERVER environment variable to caddy. It configures your application to serve the website with the caddy file-server command which doesn’t rely on a Caddyfile.

Custom run command

To override the default web server behavior, set the CC_RUN_COMMAND environment variable. When defined, it takes priority over the static server command. This is useful to run a custom server or a script before serving files.

Custom configuration and port

Caddy and SWS can be configured with a configuration file or through environment variables. You can also pass your own command line flags with CC_STATIC_FLAGS. To define a custom listen port, use CC_STATIC_PORT (default is 8080).

• Caddy configuration:
  • Command Line Arguments
  • Environment Variables
  • Caddyfile
• Static Web Server (SWS) configuration:
  • Command Line Arguments
  • Environment Variables
  • TOML Configuration File

Static Site Generators (SSG) Auto-build

If you don’t set a CC_BUILD_COMMAND, Clever Cloud tries to detect and configure the Static Site Generator (SSG) through the presence of specific files in the project root. If detected, the static website is built in the cc_static_autobuilt folder (or CC_STATIC_AUTOBUILD_OUTDIR), used as CC_WEBROOT and build cache content. If you defined a CC_WEBROOT, it will be used instead of cc_static_autobuilt.

Supported Static Site Generators (SSG) are:

Astro

• Build command: npm i && npm run astro build -- --outDir <out-dir>
• Detected file: astro.config.mjs, astro.config.ts, astro.config.js, astro.config.cjs

Docusaurus

• Build command: npm i && npm run docusaurus build -- --out-dir <out-dir>
• Detected file: docusaurus.config.js, docusaurus.config.ts

Hugo

• Build command: hugo --gc --minify --destination <out-dir>
• Detected file: hugo.toml, hugo.yaml, hugo.json

mdBook

• Build command: mdbook build --dest-dir <out-dir>
• Detected file: book.toml

MkDocs

• Build command: uvx mkdocs build --site-dir <out-dir>
• Detected file: mkdocs.yml

Nuxt.js

• Build command: npm i && npm run generate && mv .output/public <out-dir>
• Detected file: nuxt.config.ts

Storybook

• Build command: npm i && npm run build-storybook -- --output-dir <out-dir>
• Detected file: .storybook/main.js, .storybook/main.ts

VitePress

• Build command: npm i && npm run docs:build -- --outDir <out-dir>
• Detected file: .vitepress/config.js, .vitepress/config.ts, .vitepress/config.mjs, .vitepress/config.mts

Zola

• Build command: zola build --minify --output-dir <out-dir>
• Detected file: config.toml

🎓 Static Site Generators (SSG) guides

Enable health check during deployment

The healthcheck allows you to limit downtimes. Indeed, you can provide Clever Cloud with paths to check. If these paths return something other than 200, the deployment will fail.

Add one (or several) environment variable as such:

CC_HEALTH_CHECK_PATH=/my/awesome/path

Or

CC_HEALTH_CHECK_PATH_0=/my/awesome/path
CC_HEALTH_CHECK_PATH_1=/my/other/path

The deployment process checks all paths. All of them must reply with a 200 OK response code.

By default, when no environment variable (for ex: APP_HOME) is defined, the monitoring checks your repository root path /.

Example

Using the path listed above, below are the expected logs:

Response from GET /my/awesome/path is 200
Response from GET /my/other/path is 500
Health check failed:
- GET /my/other/path returned 500.
If the deployment fails after this message, please update your configuration and redeploy.

In this example, the first path is OK, but the second one failed. This gives you a hint on what failed in your application.

Best practice for healthcheck endpoints

To make the most of a healthcheck endpoint, have it check your critical dependencies. For example:

• execute SELECT 1 + 1; on your database
• retrieve a specific Cellar file
• ping a specific IP through a VPN

Request Flow: Varnish, Redirection.io, custom proxy

Request Flow automatically chains reverse proxies between port 8080 (public) and your application, managing port allocation with no manual configuration. Supported services are activated by their presence in your project:

• Varnish: add a clevercloud/varnish.vcl file or set CC_VARNISH_FILE
• Redirection.io: set CC_REDIRECTIONIO_PROJECT_KEY

Both can be active simultaneously. To control the order, set CC_REQUEST_FLOW (e.g. redirectionio,varnish). To add a custom middleware, include custom in the chain and define CC_REQUEST_FLOW_CUSTOM with @@LISTEN_PORT@@ and @@FORWARD_PORT@@ placeholders. To block public access, set CC_REQUEST_FLOW=block.

When at least one middleware is active, your application must listen on port 9000 instead of 8080.

• Learn more about Request Flow
• Learn more about Varnish on Clever Cloud
• Learn more about Redirection.io