Adding a site with a backend

Overview

This guide covers adding a site that also runs a backend service to the webserver. It assumes you have set up the webserver following the webserver setup guide.

The process is very similar to that of adding a static site, but with a few additional steps to set up the backend service.

Adding a site with a backend service

I’ll give the example of a Reflex site. This is a pure python framework that facilitates creating performant Next.js websites with a python backend and websocket communication.

This guide assumes you already have a reflex site set up.

Note

You can get started with a reflex site by running

uv init && uv add reflex
uv run reflex init

Initializing a new site

task -g web:new-backend-site SITE_NAME="new-backend-site" BACKEND_IMAGE="ghcr.io/<username>/<image-tag>" DOMAIN="some-domain.com"

This will:

• create a new directory in ~/sites/ for the new site
• create a new .caddy config file in the sites-enabled directory (locally, and on the server)
• append a service to the caddy-compose.yml file to run the backend service
  • Note: This is only updated locally for now so that changes can be made before pushing to the server.

Deploying the site

To deploy the site is the same as for a static site:

task -g web:deploy-docker-backend SITE_NAME="new-backend-site" REGISTRY="ghcr.io" USERNAME="<username>"

task -g --summary web:deploy-backend will show additional information about the task.

Updating the site

To update the site, just run the same deploy-docker-backend task again.

This can be made easier by making a task for this in the repository that has the backend service. E.g.

includes:
  # Include webserver task
  web:
    taskfile: ~/path/to/webserver/Taskfile.yml
    dir: ~/path/to/webserver-dir
    optional: true
    internal: true

tasks:
  manual_deploy_backend:
    prompt: This is normally handled by a GHA workflow. Are you sure you want to continue?
    desc: Build the backend and deploy it to the server (usually should rely on CI/CD instead)
    vars:
      SSH_NAME: "webserver"
      SITE_NAME: "new-backend-site"
    cmds:
      - task: web:deploy-docker-backend
        vars:
          SSH_NAME: "{{.SSH_NAME}}"
          SITE_NAME: "{{.SITE_NAME}}"
          PROJECT_DIR: "{{.TASKFILE_DIR}}" # Ensures the project dir is right even if task is called from a subdirectory
          DOCKERFILE_PATH: "backend.Dockerfile"  # If not using the default Dockerfile

Updating automatically via GitHub Actions

Generally, it’s better to set up an automated workflow for things like deployment.

There is a template github actions workflow other-templates/github-workflows/deploy-reflex-site.template.yml that can be copied to the .github/workflows directory in the of the site that should automatically deploy to the webserver.

You’ll want to set up an environment to add the necessary vars and secrets (in the template it assumes a production environment). See this guide on Managing environments for deployment to learn environments.

The required secrets for the template workflow are shown below, although these will likely need to be tailored to the specific project:

• Secrets:
  • RECAPTCHA_SITE_KEY – Required for generating the frontend
  • RECAPTCHA_SECRET_KEY – (may be required to run reflex to generate the frontend, but should not actually end up in the frontend static files)
  • SSH_PRIVATE_KEY – A private ssh key that grants access to the webserver (obtained via the task -g web:add-ssh-key command)
  • GITHUB_TOKEN – This is set automatically by GitHub (do not set this manually)
• Vars:
  • DROPLET_IP – The IP address of the webserver (since the GHA runner wont have the ssh alias set up)
  • SITE_NAME – The name of the site on the webserver (same as the SITE_NAME used in other tasks)
  • DOMAIN – The domain of the site (required in .env file for reflex backend)