This article walks through the thought process behind designing a minimalistic backup script in Bash. While there are robust and sophisticated backup solutions (such as zerobyte or plakar), the goal here is to build something simple and minimal. It also serves as a practical exercise for improving both design thinking and Bash scripting skills.

We won’t start entirely from scratch. Instead, we’ll use the existing todiadiyatmo/bash-backup-rotation-script as a starting point and adapt and iterate it to fit our use case.

As a sample application, we’ll use the latest MyBB forum running on PHP and MySQL, based on nemanjam/mybb-docker, deployed with Docker.

Requirements

Let’s start by clearly defining the requirements the script should fulfill so we can address them properly:

• It should back up both the database and multiple, arbitrary file assets.
• It should dump a MySQL database running inside a Docker container.
• It should assume and enforce a predefined folder structure for both the application and the backups.
• It should retain multiple, configurable daily, weekly, and monthly copies (as in the original script).
• It should support both local and remote backups.

These core requirements are enough to get us started.

Structure

At the beginning, we need to make some core decisions about how to structure the code that creates and manages backups, as well as how to organize the folder structure for the application code, backup scripts, and backup files.

Note: The terms “local” and “remote” are used relative to the server where the application being backed up is running. “Local” refers to the server’s filesystem, while “remote” refers to machines where backup copies are stored permanently. These are often devices (such as a laptop, Raspberry Pi, or home server) within a local network, so don’t be confused by the terminology.

Local and remote scripts

We prefer having local backups that can be quickly restored without needing to fetch and transfer data from a remote machine. At the same time, we also want true remote backups - synced copies stored on one or more external machines, since we treat our server instance as disposable.

There are two main approaches to this, depending on whether the primary backup script is stored and scheduled locally or on a remote machine:

1. A local backup script that creates backups and a separate script syncs them to remote machines.
2. Remote machines independently connect over SSH, send and execute the backup script on the server, and download the resulting backup.

The first approach is simpler and easier to understand, so we’ll go with that. It also provides a solid foundation if we decide to extend the system later and implement the second approach as well.

# Main, local backup script
backup-files-and-mysql.sh

# Remote sync script
backup-rsync-local.sh

However, both approaches rely on a clear, predefined folder structure, which should be explicitly validated when the script runs.

Folder structure

Bash scripts rely completely on relative paths, which means the script code and the surrounding folder structure are tightly coupled. A simple and understandable structure is a prerequisite for clean and reliable code.

Local folder structure

Below is the expected folder structure for both the server and local backups. In this context, “local” means local to the running application itself, on the same machine and file system. This backup repository serves as the source of truth for all other synchronized, remote backup copies.

Here, mybb/ is the application root directory, containing both the application files and the backup. Accordingly, mybb/backup/ is the backup directory, which includes the backup Bash scripts (mybb/backup/scripts/) and the backup data (mybb/backup/data/). The generated .zip archive contains a mysql_database/ folder for the MySQL dump, while adjacent asset folders retain their original names.

This folder structure is mandatory and fixed, as all file paths in the backup-files-and-mysql.sh script are defined relative to the script location (mybb/backup/scripts/).

Another useful detail is that the application files in mybb/ are versioned, including the backup-files-and-mysql.sh script. Since we don’t use a .env file for configuration, the production server contains an unversioned copy named backup-files-and-mysql-run.sh, which includes both the actual variables and executable code. This approach simplifies git pull operations and repository updates. Naturally, all backup data in mybb/backup/data/ is excluded from version control via .gitignore.

#  Local (server) backup folder structure:
#
# mybb/
# ├─ backup/
# │   ├─ scripts/                             - backup scripts
# │   │  ├─ backup-files-and-mysql.sh         - versioned
# │   │  └─ backup-files-and-mysql-run.sh     - current script
# │   └─ data/                                - backups data
# │      ├─ mybb_files_and_mysql-daily-2026-01-20.zip
# │      │  ├─ inc/
# │      │  ├─ images/custom/
# │      │  └─ mysql_database/
# │      │     └─ mybb.sql
# │      ├─ mybb_files_and_mysql-daily-2026-01-19.zip
# │      ├─ mybb_files_and_mysql-weekly-2026-01-14.zip
# │      └─ mybb_files_and_mysql-monthly-2026-01-01.zip
# ├── data                                    - Docker volumes
# │   ├── mybb-data                           - PHP forum files
# │   └── mysql-data                          - database data
# ├── docker-compose.yml                      - containers definitions
# |
# ...
# |
# ├── .gitignore
# └── README.md

Remote (synced) folder structure

This is the synchronized backup repository, which is considered remote from the server’s perspective. In most cases, it resides on one of our local machines where backups are stored.

As a synchronized mirror, its folder structure is identical, with one important distinction: it only contains the mybb/backup/ directory and does not include any application files, only the backups themselves. Additionally, this repository is not versioned.

#  Remote (synced) backup folder structure:
#
# mybb/
# └─ backup/
#    ├─ scripts/
#    │  └─ backup-rsync-local.sh              - current script
#    └─ data/
#       ├─ .gitkeep
#       ├─ mybb_files_and_mysql-daily-2026-01-20.zip
#       │  ├─ inc/
#       │  ├─ images/custom/
#       │  └─ mysql_database/
#       │     └─ mybb.sql
#       ├─ mybb_files_and_mysql-daily-2026-01-19.zip
#       ├─ mybb_files_and_mysql-weekly-2026-01-14.zip
#       └─ mybb_files_and_mysql-monthly-2026-01-01.zip

Local backup script

This is the main script that creates a backup on the server’s local filesystem. It dumps the MySQL database running in Docker into a plain UTF-8 .sql file and also backs up predefined application files and folders. A temporary staging folder is used to create a well-structured .zip archive.

Let’s walk through the main script responsible for creating backups of MySQL database and arbitrary application assets, section by section.

Entire script: https://github.com/nemanjam/bash-backup/blob/main/backup-files-and-mysql.sh

Configurable variables

These are the real variables that can be freely adjusted to fit a specific application and use case. Normally, they would be defined in a .env file, but for simplicity, they are hardcoded directly in the Bash script. Modifying these values does not require changing the script’s code.

The variables are fairly self-explanatory:

• DB_* - variables used for connecting to the MySQL database instance we want to back up.
• LOCAL_BACKUP_DIR - the directory where backup files are stored.
• SRC_CODE_DIRS - an associative array listing the files and directories to include in the backup.
• BACKUP_RETENTION_* - the number of daily, weekly, and monthly backups to retain.
• MAX_RETENTION - the upper limit for any BACKUP_RETENTION_* value.

# ---------- Configuration ----------

# MySQL credentials
DB_CONTAINER_NAME="mybb-database"
DB_NAME="mybb"
DB_USER="mybbuser"
DB_PASS="password"

# Note: all commands run from script dir, NEVER call cd, for relative paths to work

# Dirs paths
# Local folder is root, all other paths are relative to it
# script located at ~/traefik-proxy/apps/mybb/backup/scripts
LOCAL_BACKUP_DIR="../data"

# File or directory
# Relative to script dir, ../../ returns to: apps/mybb/
declare -A SRC_CODE_DIRS=(
    ["inc"]="../../data/mybb-data/inc/config.php"
    ["images/custom"]="../../data/mybb-data/images/custom"
)

# Retention
MAX_RETENTION=6 # 6 months for monthly backups
BACKUP_RETENTION_DAILY=3
BACKUP_RETENTION_WEEKLY=2
BACKUP_RETENTION_MONTHLY=6

Logging variables

These are additional configurable variables used specifically to control logging behavior. Since the backup script runs periodically via cron, proper logging is essential for monitoring, validation, and debugging. The last thing we want is a incorrect or misconfigured script silently producing invalid and unusable backups for months.

The variables are as follows:

• LOG_TO_FILE - a boolean that determines whether logs are written to a file or output to the terminal.
• LOG_FILE - the path to the log file.
• LOG_MAX_SIZE_MB and LOG_KEEP_SIZE_MB - used to prevent unlimited log file growth. LOG_MAX_SIZE_MB a float defining the maximum file size (in MB), after which the log is truncated, while LOG_KEEP_SIZE_MB defines the size to retain after truncation.
• LOG_TIMEZONE - the time zone used for log timestamps.

# ---------- Logging vars ----------

# Enable only when running from cron
# Cron has no TTY, interactive shell does
LOG_TO_FILE=false
[ -z "$PS1" ] && LOG_TO_FILE=true

# Log file
LOG_FILE="./log-backup-files-and-mysql.txt"

# Log size limits (MB, float allowed)
LOG_MAX_SIZE_MB=1.0   # truncate when log exceeds this
LOG_KEEP_SIZE_MB=0.5  # keep last N MB after truncation

# Timezone for log timestamps
LOG_TIMEZONE="Europe/Belgrade"

Constants

These are constant global variables, defined in a single place and reused throughout the script. Unlike configuration variables, they are not meant to be modified, as they are tightly coupled with the script’s logic. Changing them requires corresponding updates to the code.

• MYSQL_ZIP_DIR_NAME and FILES_ZIP_DIR_NAME - directory names used inside the archive.
• ZIP_PREFIX - prefix for backup archive filenames.
• FREQ_PLACEHOLDER - placeholder string to be replaced with the actual retention frequency in archive names.
• DATE - date string included in the archive filename.
• DAY_OF_* - numeric values (e.g., day of week/month) included in archive names.
• BACKUP_* - boolean flags derived from BACKUP_RETENTION_* variables.
• SCRIPT_DIR - absolute path of the current script, intended for resolving relative paths (currently unused).

# ---------- Constants ----------

# Zip vars
# Both inside zip
MYSQL_ZIP_DIR_NAME="mysql_database" 
FILES_ZIP_DIR_NAME="source_code"

# Must match backup-rsync-local.sh
ZIP_PREFIX="mybb_files_and_mysql"
FREQ_PLACEHOLDER='frequency'

DATE=$(date +"%Y-%m-%d")
ZIP_PATH="$LOCAL_BACKUP_DIR/$ZIP_PREFIX-$FREQ_PLACEHOLDER-$DATE.zip"

# Current day and weekday
DAY_OF_MONTH=$((10#$(date +%d))) # Force decimal, avoid bash octal bug on 08/09
DAY_OF_WEEK=$((10#$(date +%u))) # 1=Monday … 7=Sunday

# Must do it like this for booleans
BACKUP_DAILY=$([[ $BACKUP_RETENTION_DAILY -gt 0 ]] && echo true || echo false)
BACKUP_WEEKLY=$([[ $BACKUP_RETENTION_WEEKLY -gt 0 ]] && echo true || echo false)
BACKUP_MONTHLY=$([[ $BACKUP_RETENTION_MONTHLY -gt 0 ]] && echo true || echo false)

# Script dir absolute path, unused
# mybb/backup/scripts
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

Setup logging

At the top of the script, right below the variable and constant definitions, we conditionally call the setup_logging() function based on the LOG_TO_FILE variable. This function redirects both standard output and error output (e.g., from echo commands) to the LOG_FILE.

Additionally, it avoids a common pitfall of infinitely growing log files by truncating the file to LOG_KEEP_SIZE_MB whenever it reaches LOG_MAX_SIZE_MB. This ensures that only the most recent log entries are preserved.

# ---------- Enable logging ----------

setup_logging() {
    local max_size keep_size

    # Convert MB -> bytes (rounded down)
    max_size=$(echo "$LOG_MAX_SIZE_MB * 1024 * 1024 / 1" | bc)
    keep_size=$(echo "$LOG_KEEP_SIZE_MB * 1024 * 1024 / 1" | bc)

    # Ensure log file exists (do not truncate)
    if [ ! -f "$LOG_FILE" ]; then
        touch "$LOG_FILE"
    fi

    # Truncate log if too big
    local size size_mb
    size=$(stat -c%s "$LOG_FILE")
    size_mb=$(awk "BEGIN {printf \"%.2f\", $size/1024/1024}")  # convert bytes -> MB

    if (( size > max_size )); then
        tail -c "$keep_size" "$LOG_FILE" > "$LOG_FILE.tmp" && mv "$LOG_FILE.tmp" "$LOG_FILE"

        # Log truncation message happens before the exec redirection, so it needs its own timestamp
        echo "$(TZ="$LOG_TIMEZONE" date '+%Y-%m-%d %H:%M:%S') [INFO] Log truncated: original_size=${size_mb}MB, max_size=${LOG_MAX_SIZE_MB}MB, keep_size=${LOG_KEEP_SIZE_MB}MB" >> "$LOG_FILE"
    fi

    # Redirect stdout + stderr to log file with timestamps
    exec > >(while IFS= read -r line; do
        echo "$(TZ="$LOG_TIMEZONE" date '+%Y-%m-%d %H:%M:%S') $line"
    done >> "$LOG_FILE") 2>&1

    # Per-run separator — just echo, timestamps added automatically
    echo
    echo "========================================"
    echo "[INFO] Logging started"
    echo "[INFO] Log file: $LOG_FILE"
    echo "[INFO] Max size: ${LOG_MAX_SIZE_MB}MB, keep: ${LOG_KEEP_SIZE_MB}MB"
    echo "========================================"
    echo
}

if [ "$LOG_TO_FILE" = true ]; then
    setup_logging
fi

Validate configuration

Before executing any other logic, we validate the existence and correctness of the configuration variables and ensure that the environment meets the basic requirements needed to produce a usable and meaningful backup. The following checks are performed:

• The MySQL container is running.
• A connection to the MySQL database inside the container can be established.
• The local backup directory is defined, exists, and is not the root directory (to avoid catastrophic deletion).
• All defined asset paths exist.
• At least one of daily, weekly, or monthly backups is enabled.
• Any temporary backup archive from the previous run is deleted. This also allows the backup to be recreated and overwritten on the same day.

# ---------- Validate config ------------

is_valid_config() {
    local non_zero_found=0

    echo "[INFO] Validating configuration..."

    # Check that MySQL container is running
    if ! docker inspect -f '{{.State.Running}}' "$DB_CONTAINER_NAME" 2>/dev/null | grep -q true; then
        echo "[ERROR] MySQL container not running or not found: DB_CONTAINER_NAME=$DB_CONTAINER_NAME" >&2
        return 1
    fi

    # Check MySQL connectivity inside container
    if ! docker exec "$DB_CONTAINER_NAME" \
        mysql -u"$DB_USER" -p"$DB_PASS" "$DB_NAME" -e "SELECT 1;" >/dev/null 2>&1; then
        echo "[ERROR] MySQL connection failed: container=$DB_CONTAINER_NAME user=$DB_USER db=$DB_NAME" >&2
        return 1
    fi

    # Check local backup directory variable is set, dir exists, and is not root
    if [ -z "$LOCAL_BACKUP_DIR" ] || [ ! -d "$LOCAL_BACKUP_DIR" ] || [ "$LOCAL_BACKUP_DIR" = "/" ]; then
        echo "[ERROR] Local backup directory invalid: path=$LOCAL_BACKUP_DIR" >&2
        return 1
    fi

    # Check source code paths exist (file or directory)
    for path in "${SRC_CODE_DIRS[@]}"; do
        if [ ! -e "$path" ]; then
            echo "[ERROR] Source path missing: path=$SCRIPT_DIR/$path" >&2
            return 1
        fi
    done

    # Validate retention values
    for var in BACKUP_RETENTION_DAILY BACKUP_RETENTION_WEEKLY BACKUP_RETENTION_MONTHLY; do
        value="${!var}"

        if [[ ! "$value" =~ ^[0-9]+$ ]]; then
            echo "[ERROR] Retention value is not a number: $var=$value" >&2
            return 1
        fi

        if (( value > MAX_RETENTION )); then
            echo "[ERROR] Retention value too large: $var=$value max=$MAX_RETENTION" >&2
            return 1
        fi

        (( value > 0 )) && non_zero_found=1
    done

    if (( non_zero_found == 0 )); then
        echo "[ERROR] All retention values are zero: daily=$BACKUP_RETENTION_DAILY weekly=$BACKUP_RETENTION_WEEKLY monthly=$BACKUP_RETENTION_MONTHLY" >&2
        return 1
    fi

    # Delete existing temp backup file for this day (idempotent, can run on same day)
    if [[ -f "$ZIP_PATH" ]]; then
        rm -f "$ZIP_PATH"
        echo "[WARN] Existing temporary backup file deleted: $ZIP_PATH"
    fi

    echo "[INFO] Configuration is valid. Creating backup..."

    return 0
}

Backup logic

The create_backup() function is the core of the entire script. It assembles a MySQL database dump and file assets into a structured archive with well-organized relative paths, while also cleaning up any temporary files created during the process.

To build the archive with proper relative paths, we use a temporary STAGING_DIR directory. Inside this directory, the database dump is stored under a folder named by the MYSQL_ZIP_DIR_NAME constant, while file assets are grouped under the FILES_ZIP_DIR_NAME directory.

Using a combination of docker exec and mysqldump, we export the database contents as a plain UTF-8 .sql file and place it into the staging directory. The file is named after the database itself, using the DB_NAME configuration variable.

We then copy all asset files and directories defined in SRC_CODE_DIRS into the staging directory under the FILES_DIR parent folder. If SRC_CODE_DIRS is empty, the entire FILES_DIR directory is removed from the staging area to avoid unnecessary clutter.

Next, we create a .zip archive from STAGING_DIR using a subshell to safely change directories without affecting the main script, which would otherwise break relative path handling. Note that the script is intentionally designed to rely exclusively on relative paths. The resulting archive is saved to the ZIP_PATH location.

Finally, we remove the STAGING_DIR directory regardless of whether archive creation succeeds or fails. This ensures idempotency and prevents leftover temporary files from accumulating.

create_backup() {
    # Note: use staging dir with relative paths to have nice overview in GUI archive utility

    # Local scope
    # staging dir: mybb/backup/data/staging_dir
    # temp db dir: mybb/backup/data/staging_dir/mysql_database
    # working dir: mybb/backup/scripts
    local STAGING_DIR="$LOCAL_BACKUP_DIR/staging_dir"
    local TEMP_DB_DIR="$STAGING_DIR/$MYSQL_ZIP_DIR_NAME"
    local FILES_DIR="$STAGING_DIR/$FILES_ZIP_DIR_NAME"

    # Reset staging dir from previous broken state 
    rm -rf "$STAGING_DIR"
    mkdir -p "$TEMP_DB_DIR"  # Will recreate staging dir
    mkdir -p "$FILES_DIR"    # Folder to group all source code

    echo "[INFO] Created staging directory: $STAGING_DIR"
    echo "[INFO] Created temporary DB directory: $TEMP_DB_DIR"
    echo "[INFO] Created files directory: $FILES_DIR"

    # Dump MySQL as plain UTF-8 .sql
    docker exec "$DB_CONTAINER_NAME" sh -c \
        'mysqldump --no-tablespaces -u"$DB_USER" -p"$DB_PASS" "$DB_NAME"' \
        > "$TEMP_DB_DIR/$DB_NAME.sql"

    echo "[INFO] MySQL database dumped: db_name=$DB_NAME -> path=$TEMP_DB_DIR/$DB_NAME.sql"

    # Copy source code folders grouped into FILES_DIR dir
    for SRC_CODE_DIR in "${!SRC_CODE_DIRS[@]}"; do
        SRC_CODE_DIR_PATH="${SRC_CODE_DIRS[$SRC_CODE_DIR]}"
        cp -a "$SRC_CODE_DIR_PATH" "$FILES_DIR/"
        echo "[INFO] Added to staging: $SRC_CODE_DIR_PATH -> $FILES_ZIP_DIR_NAME/"
    done

    # Remove FILES_DIR if empty
    if [ -d "$FILES_DIR" ] && [ -z "$(ls -A "$FILES_DIR")" ]; then
        rm -rf "$FILES_DIR"
        echo "[INFO] Removed empty files directory: $FILES_DIR"
    fi

    # Create zip with clean relative paths
    # ( ... ) - subshell, cd wont affect working dir of the main script
    (
        cd "$STAGING_DIR" || {
            echo "[ERROR] Failed to cd into staging directory: $STAGING_DIR" >&2
            exit 1
        }

        # There was cd in subshell
        # Adjust zip path relative to staging_dir
        zip -r "../$ZIP_PATH" .
    ) || {
        echo "[ERROR] Zip creation failed: $ZIP_PATH" >&2
        rm -rf "$STAGING_DIR"
        exit 1
    }

    echo "[INFO] Created zip archive: $ZIP_PATH"

    # Cleanup
    rm -rf "$STAGING_DIR"
    echo "[INFO] Removed staging directory: $STAGING_DIR"
    echo "[INFO] Backup file created successfully: $ZIP_PATH"
}

The create_retention_copies() function manages retention by creating time-based copies (daily, weekly, monthly) of a freshly generated backup file. The original backup file path (ZIP_PATH) includes a placeholder string (frequency), defined by the FREQ_PLACEHOLDER constant.

For each retention option, the function evaluates the current date (e.g., Sunday for weekly, the first day of the month for monthly) and checks whether the corresponding BACKUP_* variable is enabled. If the conditions are satisfied, the original backup is copied and renamed by replacing the placeholder with the appropriate frequency.

To ensure idempotency, the function checks whether a retention copy for the current day already exists. If it does, it is removed before creating a new one, allowing the script to be safely re-run on the same day.

Finally, the temporary backup file with the placeholder name is deleted, as it is no longer needed after the retention copies are created.

create_retention_copies() {
    local IS_WEEKLY=$(( DAY_OF_WEEK == 7 )) # Sunday
    local IS_MONTHLY=$(( DAY_OF_MONTH == 1 )) # First day of month

    if [[ ! -f "$ZIP_PATH" ]]; then
        echo "[ERROR] Backup file does not exist: $ZIP_PATH"
        return 1
    fi

    for FREQ in daily weekly monthly; do
        case "$FREQ" in
            daily)
                [[ "$BACKUP_DAILY" == true ]] || continue
                ;;
            weekly)
                [[ "$IS_WEEKLY" -eq 1 && "$BACKUP_WEEKLY" == true ]] || continue
                ;;
            monthly)
                [[ "$IS_MONTHLY" -eq 1 && "$BACKUP_MONTHLY" == true ]] || continue
                ;;
        esac

        # Placeholder 'frequency' string replacement
        TARGET_FILE="${ZIP_PATH/$FREQ_PLACEHOLDER/$FREQ}"

        # Delete existing backup for this frequency (idempotent, can run on same day)
        if [[ -f "$TARGET_FILE" ]]; then
            rm -f "$TARGET_FILE"
            echo "[WARN] Existing $FREQ backup removed: $TARGET_FILE"
        fi

        cp "$ZIP_PATH" "$TARGET_FILE"
        echo "[INFO] $FREQ backup copied successfully: $TARGET_FILE"
    done

    rm -f "$ZIP_PATH"
    echo "[INFO] Removed temporary backup file: $ZIP_PATH"
}

We don’t want to accumulate an unlimited number of backup copies; instead, we delete outdated ones according to the retention limits defined by the BACKUP_RETENTION_* variables.

The prune_old_backups() function enforces these retention limits by removing older backups for each frequency (daily, weekly, monthly).

Based on the BACKUP_RETENTION_* variables, we dynamically calculate the RETENTION integer value for each frequency. If it is zero or unset, we exit early from the loop.

We then list the contents of the LOCAL_BACKUP_DIR and delete outdated copies by processing the output of the ls command through a pipeline:

• We filter out files that do not contain values from the ZIP_PREFIX and FREQ variables.
• We skip the first RETENTION lines, which effectively keeps the RETENTION most recent backups.
• Using xargs and rm -R, we delete all remaining filenames line by line, ignoring any error messages to keep logs clean.

prune_old_backups() {
    for FREQ in daily weekly monthly; do
        # Determine retention variable dynamically
        RETENTION_VAR="BACKUP_RETENTION_${FREQ^^}"  # uppercase: daily -> DAILY
        RETENTION="${!RETENTION_VAR}"

        # Skip if retention is zero or unset
        [[ -z "$RETENTION" || "$RETENTION" -le 0 ]] && continue

        # Find old backups and delete them
        ls -t "$LOCAL_BACKUP_DIR" \
            | grep "$ZIP_PREFIX" \
            | grep "$FREQ" \
            | sed -e 1,"$RETENTION"d \
            | xargs -d '\n' -I{} rm -R "$LOCAL_BACKUP_DIR/{}" > /dev/null 2>&1

        echo "[INFO] Pruned $FREQ backups, keeping last $RETENTION"
    done
}

Main invocation

Finally, we invoke the functions defined above.

First, we ensure that all required configuration is correct. If validation fails, the script prints an error message to stderr and immediately exits with a non-zero status, preventing any further execution.

If the configuration is valid, the script continues by creating a backup archive, then generating additional retention copies, and finally removing old backups.

# ---------- Main script ----------

if ! is_valid_config; then
    echo "[ERROR] Configuration validation failed. Aborting backup." >&2
    exit 1
fi

create_backup

create_retention_copies

prune_old_backups

echo "[INFO] Backup completed successfully."

Below is an example log entry from a successful run when creating a backup:

2026-04-07 00:30:01 ========================================
2026-04-07 00:30:01 [INFO] Logging started
2026-04-07 00:30:01 [INFO] Log file: ./log-backup-files-and-mysql.txt
2026-04-07 00:30:01 [INFO] Max size: 1.0MB, keep: 0.5MB
2026-04-07 00:30:01 ========================================
2026-04-07 00:30:01 
2026-04-07 00:30:01 [INFO] Validating configuration...
2026-04-07 00:30:01 [INFO] Configuration is valid. Creating backup...
2026-04-07 00:30:01 [INFO] Created staging directory: ../data/staging_dir
2026-04-07 00:30:01 [INFO] Created temporary DB directory: ../data/staging_dir/mysql_database
2026-04-07 00:30:01 [INFO] Created files directory: ../data/staging_dir/source_code
2026-04-07 00:30:01 mysqldump: [Warning] Using a password on the command line interface can be insecure.
2026-04-07 00:30:02 [INFO] MySQL database dumped: db_name=mybb -> path=../data/staging_dir/mysql_database/mybb.sql
2026-04-07 00:30:02 [INFO] Added to staging: ../../data/mybb-data/images/custom -> source_code/
2026-04-07 00:30:02 [INFO] Added to staging: ../../data/mybb-data/inc/config.php -> source_code/
2026-04-07 00:30:02   adding: mysql_database/ (stored 0%)
2026-04-07 00:30:02   adding: mysql_database/mybb.sql (deflated 83%)
2026-04-07 00:30:02   adding: source_code/ (stored 0%)
2026-04-07 00:30:02   adding: source_code/config.php (deflated 62%)
2026-04-07 00:30:02   adding: source_code/custom/ (stored 0%)
2026-04-07 00:30:02   adding: source_code/custom/logo-blue-153x75.png (stored 0%)
2026-04-07 00:30:02   adding: source_code/custom/logo-blue-588x288.png (deflated 0%)
2026-04-07 00:30:02 [INFO] Created zip archive: ../data/mybb_files_and_mysql-frequency-2026-04-07.zip
2026-04-07 00:30:02 [INFO] Removed staging directory: ../data/staging_dir
2026-04-07 00:30:02 [INFO] Backup file created successfully: ../data/mybb_files_and_mysql-frequency-2026-04-07.zip
2026-04-07 00:30:02 [INFO] daily backup copied successfully: ../data/mybb_files_and_mysql-daily-2026-04-07.zip
2026-04-07 00:30:02 [INFO] Removed temporary backup file: ../data/mybb_files_and_mysql-frequency-2026-04-07.zip
2026-04-07 00:30:02 [INFO] Pruned daily backups, keeping last 3
2026-04-07 00:30:02 [INFO] Pruned weekly backups, keeping last 2
2026-04-07 00:30:02 [INFO] Pruned monthly backups, keeping last 6
2026-04-07 00:30:02 [INFO] Backup completed successfully.

Remote syncing script

Besides the main backup script running directly on the server, we use an additional script that replicates the original backup on remote machines.

This script synchronizes the backups created on the server (which serves as the source of truth) to remote machines used for storing backup copies. It connects to the server via SSH, validates both the backup and local folder structure, and finally synchronizes the data using the rsync command.

Entire script: https://github.com/nemanjam/bash-backup/blob/main/backup-rsync-local.sh

Configurable variables

Similarly to the local scripts, these are configurable variables that would typically be defined in a .env file. They are used to configure the synchronization script.

• REMOTE_HOST - the server host used for the SSH and rsync connections.
• REMOTE_BACKUP_DIR - the absolute path (avoid shell expansion) to the backup directory on the server (source of truth).
• LOCAL_BACKUP_DIR - the relative path to the local directory where backups are synchronized.
• MIN_BACKUP_SIZE_MB - a human-readable float value (in MB) representing the minimum valid backup size.
• MIN_BACKUP_SIZE_BYTES - the equivalent integer value in bytes, used for actual validation and computations.

# ---------- Configuration ----------

REMOTE_HOST="arm2"
# Full, absolute path - can't use ~/, used both locally and remote with ssh/rsync
REMOTE_BACKUP_DIR="/home/ubuntu/traefik-proxy/apps/mybb/backup/data"

# Note: all commands run from script dir, NEVER call cd, for relative LOCAL paths to work
LOCAL_BACKUP_DIR="../data"

# Minimum valid backup size, ZIP size, compressed
# Only db for blank forum, zip=158.2 KiB
# Float
MIN_BACKUP_SIZE_MB=0.1
# Integer
MIN_BACKUP_SIZE_BYTES=$(echo "$MIN_BACKUP_SIZE_MB * 1024 * 1024 / 1" | bc) # rounded to integer

Constants

The only constant used is ZIP_PREFIX and it must match the one used in backup creation script backup-files-and-mysql.sh.

# ---------- Constants ----------

# Must match backup-files-and-mysql.sh
ZIP_PREFIX="mybb_files_and_mysql"

# Script dir absolute path, unused
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

Logging variables

These are the same as in the Local backup script. The logging format is identical in both the local and remote scripts.

# ---------- Logging vars ----------

# Enable only when running from cron
# Cron has no TTY, interactive shell does
LOG_TO_FILE=false
[ -z "$PS1" ] && LOG_TO_FILE=true

# Log file
LOG_FILE="./log-backup-rsync-local.txt"

# Log size limits (MB, float allowed)
LOG_MAX_SIZE_MB=1.0   # truncate when log exceeds this
LOG_KEEP_SIZE_MB=0.5  # keep last N MB after truncation

# Timezone for log timestamps
LOG_TIMEZONE="Europe/Belgrade"

Setup logging

Identical as in the local script.

Validate configuration

Same as in the local script, we validate the existence and correctness of the configuration variables before performing any other logic. In this case, we ensure that:

• The SSH connection to the remote host can be established.
• The remote backup directory exists.
• The local backup directory exists.

# ---------- Validate config ------------

is_valid_config() {
    echo "----------------------------------------"
    echo "[INFO] Validating configuration"

    # Check SSH connectivity to remote host
    if ! ssh -o BatchMode=yes -o ConnectTimeout=5 "$REMOTE_HOST" "true" >/dev/null 2>&1; then
        echo "[ERROR] Cannot connect to remote host via SSH: REMOTE_HOST=$REMOTE_HOST" >&2
        return 1
    fi
    echo "[INFO] SSH connection established: REMOTE_HOST=$REMOTE_HOST"

    # Check remote backup directory exists
    if ! ssh "$REMOTE_HOST" "[ -d \"$REMOTE_BACKUP_DIR\" ]" >/dev/null 2>&1; then
        echo "[ERROR] Remote backup directory does not exist: REMOTE_HOST=$REMOTE_HOST REMOTE_BACKUP_DIR=$REMOTE_BACKUP_DIR" >&2
        return 1
    fi
    echo "[INFO] Remote backup directory exists: $REMOTE_BACKUP_DIR"

    # Check local backup directory exists
    if [ ! -d "$LOCAL_BACKUP_DIR" ]; then
        echo "[ERROR] Local backup directory does not exist: path=$SCRIPT_DIR/$LOCAL_BACKUP_DIR" >&2
        return 1
    fi
    echo "[INFO] Local backup directory exists: $SCRIPT_DIR/$LOCAL_BACKUP_DIR"

    echo "[INFO] Configuration validation successful"
    echo "----------------------------------------"

    return 0
}

Utility functions

Besides validating configuration variables, we also need to validate the remote backup on the server before syncing locally. This is a more complex task, so we break it down into a few smaller, reusable utility functions for clarity and readability.

• get_latest_date() expects a list of filenames via stdin, extracts the date part in YYYY-MM-DD format, sorts them in descending order, and returns the top item, which is the latest date in the list.
• split_backup_types() accepts a list of filenames as a single string (e.g. output from ls) as the first argument. The second argument is a mutable associative array passed by reference, used to store the result. The function parses the raw input string and groups backup filenames into categories (daily, weekly, monthly), storing each group in the corresponding key of the associative array.
• check_count() compares remote and local backup counts (for a given type). If the remote count is lower than the local count, it prints an error and returns failure.
• check_date() does the same for dates. If the latest remote backup date is older than the latest local backup date, it prints an error and returns failure.
• bytes_to_human() converts a size in bytes into a human-readable format (KB, MB, GB). It is used to improve log readability.
• check_file_size() validates that all remote backup files meet a minimum size requirement. It fetches file names and sizes from the remote server via SSH and iterates through each file. For each one, it logs the size and checks whether it is smaller than the minimum allowed size MIN_BACKUP_SIZE_BYTES. If any file is too small, it logs the filename and exits early with an error.

# ------------ Utils ------------

# Extract latest YYYY-MM-DD date from backup filenames
get_latest_date() {
    sed -E 's/.*-([0-9]{4}-[0-9]{2}-[0-9]{2})\.zip/\1/' \
        | sort | tail -n 1
}

# Split a list of filenames into daily/weekly/monthly assoc array
split_backup_types() {
    local files="$1"
    declare -n arr=$2  # pass assoc array by name

    while IFS= read -r file; do
        case "$file" in
            *-daily-*.zip)   arr[daily]+="$file"$'\n' ;;
            *-weekly-*.zip)  arr[weekly]+="$file"$'\n' ;;
            *-monthly-*.zip) arr[monthly]+="$file"$'\n' ;;
        esac
    done <<< "$files"
}

# Ensure remote has at least as many backups as local
check_count() {
    local remote_count="$1"
    local local_count="$2"
    local backup_type="$3"

    if (( remote_count < local_count )); then
        echo "ERROR: remote has fewer type=$backup_type backups than local, remote_count=$remote_count, local_count=$local_count"
        return 1
    fi
}

# Ensure remote backups are not older than local
check_date() {
    local remote_latest="$1"
    local local_latest="$2"
    local backup_type="$3"

    if [[ -n "$local_latest" && "$remote_latest" < "$local_latest" ]]; then
        echo "ERROR: remote type=$backup_type backup is older than local, remote_latest=$remote_latest, local_latest=$local_latest"
        return 1
    fi
}

# Convert bytes to human-readable format
bytes_to_human() {
    local size=$1
    if (( size < 1024 )); then
        echo "${size}B"
    elif (( size < 1024*1024 )); then
        echo "$((size/1024))KB"
    elif (( size < 1024*1024*1024 )); then
        echo "$((size/1024/1024))MB"
    else
        echo "$((size/1024/1024/1024))GB"
    fi
}

# Ensure all remote backups are larger than minimum size
check_file_size() {
    local bad_file bad_file_size
    local remote_file size
    local remote_files_info

    # Store SSH output in a variable
    remote_files_info=$(ssh "$REMOTE_HOST" "
        for f in $REMOTE_BACKUP_DIR/${ZIP_PREFIX}-*.zip; do
            [ -f \"\$f\" ] || continue
            stat -c '%n %s' \"\$f\"
        done
    ")

    # Iterate over each line in the variable
    while read -r remote_file size; do
        echo "[INFO] Remote file: $remote_file, size=$(bytes_to_human $size)"

        if (( size < MIN_BACKUP_SIZE_BYTES )); then
            bad_file="$remote_file"
            bad_file_size="$size"
            break
        fi
    done <<< "$remote_files_info"

    if [[ -n "$bad_file" ]]; then
        echo "ERROR: remote backup file too small: $bad_file, size=$(bytes_to_human $bad_file_size), min=$(bytes_to_human $MIN_BACKUP_SIZE_BYTES)"
        return 1
    fi

    echo "[INFO] All remote backup files meet minimum size, min=$(bytes_to_human $MIN_BACKUP_SIZE_BYTES)"
    return 0
}

Validate source of truth

The is_valid_backup() function is the final check before synchronization. It validates both remote (source of truth) and local backups, compares them for consistency, and ensures that we do not accidentally overwrite the local backup with a corrupted or inconsistent remote backup from the server. It composes the utility functions defined above and adds its own logic:

• It verifies that all remote backup files meet a minimum size requirement.
• For each backup type (daily, weekly, monthly), it ensures that:
  • The remote contains more backups than the local.
  • The latest backup date on the remote is newer than the latest local backup.

If any validation fails, the function prints an error and exits early with a non-zero status. If all checks pass, it confirms successful validation and returns success.

# ---------- Validation ----------

is_valid_backup() {
    echo "----------------------------------------"
    echo "[INFO] Validating backups"

    # Local variables
    local -A remote_lists local_lists
    local remote_all_files local_all_files

    # Loop variables
    local backup_type
    local remote_list local_list
    local remote_count local_count
    local remote_latest local_latest

    # Global size validation (run once)
    if ! check_file_size; then
        echo "ERROR: remote backup contains file(s) smaller than minimum size, min=$(bytes_to_human $MIN_BACKUP_SIZE_BYTES)"
        return 1
    fi
    echo "[INFO] Remote backup file sizes validated, min=$(bytes_to_human $MIN_BACKUP_SIZE_BYTES)"

    # Store remote backup filenames in a variable and split, ignores .gitkeep
    remote_all_files=$(ssh "$REMOTE_HOST" "ls -1 $REMOTE_BACKUP_DIR/${ZIP_PREFIX}-*.zip 2>/dev/null")
    split_backup_types "$remote_all_files" remote_lists
	echo "[INFO] Remote backup file list loaded for type(s):"
	echo "$remote_all_files"

    # Store local backup filenames in a variable and split
    local_all_files=$(ls -1 "$LOCAL_BACKUP_DIR/${ZIP_PREFIX}-*.zip" 2>/dev/null)
    split_backup_types "$local_all_files" local_lists
	echo "[INFO] Local backup file list loaded:"
	echo "$local_all_files"

    for backup_type in daily weekly monthly; do
        echo "[INFO] Checking backup type: $backup_type"

        # Set filename lists
        remote_list="${remote_lists[$backup_type]}"
        local_list="${local_lists[$backup_type]}"

        # Check counts
        remote_count=$(echo "$remote_list" | grep -c . || true)
        local_count=$(echo "$local_list" | grep -c . || true)
        if ! check_count "$remote_count" "$local_count" "$backup_type"; then
            echo "ERROR: backup count mismatch for type=$backup_type: remote=$remote_count is less than local=$local_count"
            return 1
        fi
        echo "[INFO] Backup count valid: type=$backup_type remote=$remote_count local=$local_count"

        # Check latest dates
        remote_latest=$(echo "$remote_list" | get_latest_date)
        local_latest=$(echo "$local_list" | get_latest_date)
        if ! check_date "$remote_latest" "$local_latest" "$backup_type"; then
            echo "ERROR: latest backup date mismatch for type=$backup_type: remote=$remote_latest is older than local=$local_latest"
            return 1
        fi
        echo "[INFO] Latest backup date valid: type=$backup_type date=$remote_latest"
    done

    echo "[INFO] Backup validation successful"
    echo "----------------------------------------"

    return 0
}

Synchronizing local copy

Finally, we can invoke the validation functions from above and synchronize remote backup to the local machine.

It first verifies that the configuration is valid, and then that the remote backups are valid. If any validation fails, the script aborts and logs error message.

If both checks pass, it proceeds to mirror the remote backup directory locally using rsync, preserving structure and deleting any local files that no longer exist on the remote.

# ---------- Sync ----------

if ! is_valid_config; then
    echo "[ERROR] Configuration validation failed. Aborting script." >&2
    exit 1
fi

# Exit early if remote backup is not valid
if ! is_valid_backup; then
    echo "ERROR: Backup validation failed - aborting"
    exit 1
fi

# Note: no fallback logic for now

echo "[INFO] Remote backup valid - syncing data"

# Mirror remote data directory locally
rsync -ah --progress --delete "$REMOTE_HOST:$REMOTE_BACKUP_DIR/" "$LOCAL_BACKUP_DIR/"

echo "[INFO] Backup sync completed successfully."

Below is an example log entry from a successful run when synchronizing a backup:

2026-04-07 00:45:02 ========================================
2026-04-07 00:45:02 [INFO] Logging started
2026-04-07 00:45:02 [INFO] Log file: ./log-backup-rsync-local.txt
2026-04-07 00:45:02 [INFO] Max size: 1.0MB, keep: 0.5MB
2026-04-07 00:45:02 ========================================
2026-04-07 00:45:02 
2026-04-07 00:45:02 ----------------------------------------
2026-04-07 00:45:02 [INFO] Validating configuration
2026-04-07 00:45:03 [INFO] SSH connection established: REMOTE_HOST=arm2
2026-04-07 00:45:04 [INFO] Remote backup directory exists: / ... /traefik-proxy/apps/mybb/backup/data
2026-04-07 00:45:04 [INFO] Local backup directory exists: / ... /mybb-backup/scripts/../data
2026-04-07 00:45:04 [INFO] Configuration validation successful
2026-04-07 00:45:04 ----------------------------------------
2026-04-07 00:45:04 ----------------------------------------
2026-04-07 00:45:04 [INFO] Validating backups
2026-04-07 00:45:05 [INFO] Remote file: / ... /traefik-proxy/apps/mybb/backup/data/mybb_files_and_mysql-daily-2026-04-05.zip, size=279KB
2026-04-07 00:45:05 [INFO] Remote file: / ... /traefik-proxy/apps/mybb/backup/data/mybb_files_and_mysql-daily-2026-04-06.zip, size=293KB
2026-04-07 00:45:05 [INFO] Remote file: / ... /traefik-proxy/apps/mybb/backup/data/mybb_files_and_mysql-daily-2026-04-07.zip, size=285KB
2026-04-07 00:45:05 [INFO] Remote file: / ... /traefik-proxy/apps/mybb/backup/data/mybb_files_and_mysql-monthly-2026-02-01.zip, size=292KB
2026-04-07 00:45:05 [INFO] Remote file: / ... /traefik-proxy/apps/mybb/backup/data/mybb_files_and_mysql-monthly-2026-03-01.zip, size=334KB
2026-04-07 00:45:05 [INFO] Remote file: / ... /traefik-proxy/apps/mybb/backup/data/mybb_files_and_mysql-monthly-2026-04-01.zip, size=332KB
2026-04-07 00:45:05 [INFO] Remote file: / ... /traefik-proxy/apps/mybb/backup/data/mybb_files_and_mysql-weekly-2026-03-22.zip, size=326KB
2026-04-07 00:45:05 [INFO] Remote file: / ... /traefik-proxy/apps/mybb/backup/data/mybb_files_and_mysql-weekly-2026-04-05.zip, size=279KB
2026-04-07 00:45:05 [INFO] All remote backup files meet minimum size, min=102KB
2026-04-07 00:45:05 [INFO] Remote backup file sizes validated, min=102KB
2026-04-07 00:45:06 [INFO] Remote backup file list loaded for type(s):
2026-04-07 00:45:06 / ... /traefik-proxy/apps/mybb/backup/data/mybb_files_and_mysql-daily-2026-04-05.zip
2026-04-07 00:45:06 / ... /traefik-proxy/apps/mybb/backup/data/mybb_files_and_mysql-daily-2026-04-06.zip
2026-04-07 00:45:06 / ... /traefik-proxy/apps/mybb/backup/data/mybb_files_and_mysql-daily-2026-04-07.zip
2026-04-07 00:45:06 / ... /traefik-proxy/apps/mybb/backup/data/mybb_files_and_mysql-monthly-2026-02-01.zip
2026-04-07 00:45:06 / ... /traefik-proxy/apps/mybb/backup/data/mybb_files_and_mysql-monthly-2026-03-01.zip
2026-04-07 00:45:06 / ... /traefik-proxy/apps/mybb/backup/data/mybb_files_and_mysql-monthly-2026-04-01.zip
2026-04-07 00:45:06 / ... /traefik-proxy/apps/mybb/backup/data/mybb_files_and_mysql-weekly-2026-03-22.zip
2026-04-07 00:45:06 / ... /traefik-proxy/apps/mybb/backup/data/mybb_files_and_mysql-weekly-2026-04-05.zip
2026-04-07 00:45:06 [INFO] Local backup file list loaded:
2026-04-07 00:45:06 
2026-04-07 00:45:06 [INFO] Checking backup type: daily
2026-04-07 00:45:06 [INFO] Backup count valid: type=daily remote=3 local=0
2026-04-07 00:45:06 [INFO] Latest backup date valid: type=daily date=2026-04-07
2026-04-07 00:45:06 [INFO] Checking backup type: weekly
2026-04-07 00:45:06 [INFO] Backup count valid: type=weekly remote=2 local=0
2026-04-07 00:45:06 [INFO] Latest backup date valid: type=weekly date=2026-04-05
2026-04-07 00:45:06 [INFO] Checking backup type: monthly
2026-04-07 00:45:06 [INFO] Backup count valid: type=monthly remote=3 local=0
2026-04-07 00:45:06 [INFO] Latest backup date valid: type=monthly date=2026-04-01
2026-04-07 00:45:06 [INFO] Backup validation successful
2026-04-07 00:45:06 ----------------------------------------
2026-04-07 00:45:06 [INFO] Remote backup valid - syncing data
2026-04-07 00:45:07 receiving incremental file list
2026-04-07 00:45:07 deleting mybb_files_and_mysql-daily-2026-04-04.zip
2026-04-07 00:45:07 ./
2026-04-07 00:45:07 mybb_files_and_mysql-daily-2026-04-07.zip
2026-04-07 00:45:07 
              0   0%    0.00kB/s    0:00:00  
        292.31K 100%    1.91MB/s    0:00:00 (xfr#1, to-chk=5/10)
2026-04-07 00:45:07 [INFO] Backup sync completed successfully.

Cron jobs

Now that we have implemented the scripts, we just need to schedule them to run daily by defining cron jobs on the server and on each machine that stores synced copies.

As a reminder, we can list and edit cron jobs using the following commands:

# List crons
crontab -l

# Edit crons
crontab -e

We need to carefully choose times that capture application data near the end of the day in our target time zone. The sync script must run after the backup creation script, so we need to estimate the execution time of the backup process and schedule the sync within a safe margin. With this in mind, we can schedule the backup at 23:30 and the sync at 23:45.

Another important detail is that both scripts rely on relative paths, so cron must execute them from the correct working directory. This can be achieved with cd /.../backup/scripts && bash ./my-script.sh. Additionally, we should use absolute paths in the cron configuration (avoiding shortcuts like ~ for the home directory), as such expansions may fail in a cron environment.

On server:

# Create backup every day at 23:30 Belgrade (UTC+2) time (21:30 UTC)
30 21 * * * cd /home/username/traefik-proxy/apps/mybb/backup/scripts && /usr/bin/bash ./run-backup-files-and-mysql.sh

On syncing machines:

# Sync backup every day at 23:45 Belgrade (UTC+2) time (21:45 UTC)
45 21 * * * cd /home/username/mybb-backup/scripts && /usr/bin/bash ./run-backup-rsync-local.sh

Interestingly, I couldn’t find a reliable way to set a custom time zone for cron jobs. I tried setting the TZ and CRON_TZ variables, but they were ignored, and cron always fell back to UTC.

# None of these actually sets the time zone successfully
# Always falls back to UTC

# Global
TZ=Europe/Belgrade
CRON_TZ=Europe/Belgrade

# Per job
30 21 * * * TZ=Europe/Belgrade cd /home/username/traefik-proxy/apps/mybb/backup/scripts && /usr/bin/bash ./run-backup-files-and-mysql.sh
30 21 * * * CRON_TZ=Europe/Belgrade cd /home/username/traefik-proxy/apps/mybb/backup/scripts && /usr/bin/bash ./run-backup-files-and-mysql.sh

Room for improvements

We described an example implementation along with the thought process behind designing a usable backup script. It is certainly not perfect or final, and it can be enhanced and improved in a number of ways. Here are some possible improvements:

• Extract all configuration variables from the script and load them from an .env file.
• Add an ENABLE_ASSETS boolean flag to enable or disable including application file assets in the backup. Currently, this requires commenting out all keys in the SRC_CODE_DIRS associative array.
• Create a decentralized solution by avoiding a single “source of truth” backup on the server. Instead, allow local backup repositories to connect to the server via SSH and execute code that creates a temporary backup, which can then be downloaded locally and deleted afterward. In practice, backup-rsync-local.sh would send and execute the backup-files-and-mysql.sh script remotely and clean up the temporary backup after downloading.
• Set up a test environment with sample data to conveniently test and validate the scripts without waiting for scheduled time intervals (daily, weekly, monthly copies).
• Find a reliable and actually working solution for configuring the time zone for cron jobs on Ubuntu.

Completed code

• Backup script: https://github.com/nemanjam/bash-backup
• Example application: https://github.com/nemanjam/mybb-docker

Conclusion

The assumption was that we need to track the state of an application, including the database, configuration (source files), and assets (images), and that we need a simple, minimalistic, yet functional solution. Although this is a quite common use case, after searching I couldn’t find a convincing, up-to-date Bash script for this purpose. So, I decided to build upon and adapt the closest existing script I could find. That process is described in this article.

This is a pragmatic, custom script focused on simplicity, with no ambition to become a comprehensive backup solution covering many use cases and features. Such a solution would require a much larger scope of work, and many robust backup tools already exist.

How do you approach creating and managing backups for your applications? Let me know in the comments.

References

• The original script https://github.com/todiadiyatmo/bash-backup-rotation-script
• Crontab set custom time zone https://serverfault.com/questions/848829/how-to-use-timezone-with-cron-tab

Many of you can probably guess the point of this article just by reading the title, but it’s still useful to have a clear reminder backed by some real-world measurements. This will be a practical, straight-to-the-point article.

The problem with scp in deployments

When copying the dist folder to a deployment server, the first instinct is usually to clear the existing folder and upload the new one using scp. While this works, you can achieve significant long-term improvements by replacing a few lines and using rsync instead.

The important facts to keep in mind are:

1. This is a repeated operation.
2. The server will (almost) always already contain a previous copy of the dist folder.
3. Not all files in the build artifacts change on every build, many remain exactly the same and can be reused.

Clearing the dist folder and scp the entire content each time simply ignores the facts above. scp it is not optimized for repeated copying where most files remain unchanged.

Bash deployment scripts and Github Actions deployment workflows run frequently, so any unnecessary time or performance overhead accumulates and wastes energy and resources. It’s important to optimize as much as possible, especially when it requires very little effort.

Why rsync is faster

rsync is designed specifically for efficient file synchronization. Instead of copying everything every time, it compares the source and destination and transfers only the files that have changed.

This dramatically reduces the amount of data that needs to be sent during deployments. In most cases, only a small subset of files changes between builds, which means rsync can complete the transfer much faster than scp.

Another advantage is that rsync can resume partially transferred files and optionally compress data during transfer. These features make it especially well suited for automated deployment workflows where speed and reliability are important.

rsync flags for deployments

A typical rsync command used in deployments looks like this:

rsync -az --delete ./dist/ user@server:/var/www/site

Some commonly used flags include:

• -a (archive) preserves permissions, timestamps, and recursively copies files.
• -z enables compression during transfer, which reduces network usage.
• --delete removes files on the destination that no longer exist in the source, keeping the deployment directory in sync.
• --partial allows interrupted transfers to resume instead of restarting from scratch.

Together, these options make rsync a powerful and efficient tool for copying build artifacts during automated deployments.

A complete list of options is available in the command’s manual: https://download.samba.org/pub/rsync/rsync.1#OPTION_SUMMARY.

Example: deployment with scp

For both scp and rsync, we will consider two examples: a Bash script used to deploy from a local development environment, and a Github Actions workflow. These represent two common approaches to deployments.

For the sake of context and completeness, the full scripts are included so you can reuse them or run your own tests and performance comparisons.

Bash script

Naturally, the only truly important part is the scp line. However, let’s briefly review the rest of the script, since it demonstrates what we would typically use in a real-world scenario.

The first assumption is that we have a local dist folder containing the compiled application built with a local .env file, and an Nginx web server with a webroot directory on a remote server. Our Bash script accepts three input arguments: LOCAL_PATH, REMOTE_PATH, and REMOTE_HOST, which we validate before performing the copy.

Next, we establish an initial ssh connection to delete the existing application artifacts from the previous deployment. During this step, we also log some information by printing the file list and the total number of files in the Nginx webroot before and after removing the old files.

Note 1: When removing old artifacts, we delete the contents of the Nginx webroot directory, not the webroot directory itself. Removing the directory could disrupt the current Nginx session and would require restarting the Nginx process or container.

Note 2: Below the scp line, I also include a tar ... | ssh command example that compresses the artifacts before piping them through the SSH connection. In theory, this should provide performance similar to rsync in scenarios where we always completely clear the previous deployment. I will include it in the measurements so we can see how it performs.

# Navigate to ~/traefik-proxy/apps/nmc-nginx-with-volume/website
cd $REMOTE_PATH

# Clear the contents, not the `/website` path segment
rm -rf * 

https://github.com/nemanjam/nemanjam.github.io/blob/main/scripts/deploy-nginx.sh

#!/bin/bash

LOCAL_PATH="./dist"
# REMOTE_PATH="~/traefik-proxy/apps/nmc-nginx-with-volume/website"
# REMOTE_HOST="arm1"

REMOTE_PATH=$1
REMOTE_HOST=$2

# Check if all arguments are provided
if [[ -z "$REMOTE_PATH" || -z "$REMOTE_HOST" ]]; then
  echo "Incorrect args, usage: $0 <remote_path> <remote_host>"
  exit 1
fi

# Navigate to the website folder on the remote server and clear contents of the website folder
ssh $REMOTE_HOST "cd $REMOTE_PATH && \
                  echo 'Listing files before clearing:' && \
                  echo 'List before clearing:' && \
                  ls && \
                  echo 'Count before clearing:' && \
                  ls -l | grep -v ^l | wc -l && \

                  # Only possible to skip with rsync --delete

                  echo 'Clearing contents of the folder...' && \
                  rm -rf * && \
                  echo 'List after clearing:' && \
                  ls && \
                  echo 'Count after clearing:' && \
                  find . -type f | wc -l && \

                  echo 'Copying new contents...'"

# Copy new contents, 320 MB
# Using scp -rq, slowest, not resumable
scp -rq $LOCAL_PATH/* $REMOTE_HOST:$REMOTE_PATH

# Using tar, fast for cleaned dir
# tar cf - -C "$LOCAL_PATH" . | ssh "$REMOTE_HOST" "tar xvf - -C $REMOTE_PATH" >/dev/null 2>&1

Then we can call the Bash script like this by passing REMOTE_PATH and REMOTE_HOST arguments:

{
  "scripts": {
    // ...

    "deploy:nginx:rpi": "bash scripts/deploy-nginx.sh '~/traefik-proxy/apps/nmc-nginx-with-volume/website' rpi",
    
    // ...
  }
}

Github Actions

The Github Actions workflow provides even more context. It includes environment variables required by the application, sets up Node.js and pnpm, and builds the app. The rest is identical to the Bash script above: we use the appleboy/ssh-action action to establish an SSH connection and clear the previous deployment, and the appleboy/scp-action action to copy the built dist/ folder to the remote server using scp.

In the scp step, most arguments are self-explanatory, but one worth emphasizing is strip_components: 1. This prevents creating an additional dist/ path segment inside the Nginx webroot. In other words, we want the files copied to nmc-nginx-with-volume/website/*, not to nmc-nginx-with-volume/website/dist/*.

https://github.com/nemanjam/nemanjam.github.io/blob/main/.github/workflows/default__deploy-nginx-scp.yml

name: Deploy Nginx scp

on:
  push:
    branches:
      - 'main'
    tags:
      - 'v[0-9]+.[0-9]+.[0-9]+'
  pull_request:
    branches:
      - 'disabled-main'
  workflow_dispatch:

env:
  SITE_URL: 'https://nemanjamitic.com'
  PLAUSIBLE_SCRIPT_URL: 'https://plausible.arm1.nemanjamitic.com/js/script.js'
  PLAUSIBLE_DOMAIN: 'nemanjamitic.com'

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          fetch-depth: 1

      - name: Print commit id, message and tag
        run: |
          git show -s --format='%h %s'
          echo "github.ref -> {{ github.ref }}"

      - name: Set up Node.js and pnpm
        uses: actions/setup-node@v4
        with:
          node-version: 24.13.0
          registry-url: 'https://registry.npmjs.org'

      - name: Install pnpm
        uses: pnpm/action-setup@v4
        with:
          version: 10.30.1

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      - name: Build nemanjamiticcom
        run: pnpm build

      - name: Clean up website dir
        uses: appleboy/ssh-action@master
        with:
          host: ${{ secrets.REMOTE_HOST }}
          username: ${{ secrets.REMOTE_USERNAME }}
          key: ${{ secrets.REMOTE_KEY_ED25519 }}
          port: ${{ secrets.REMOTE_PORT }}
          script_stop: true
          script: |
            cd /home/ubuntu/traefik-proxy/apps/nmc-nginx-with-volume/website
            echo "Content before deletion: $(pwd)"
            ls -la
            rm -rf ./*
            echo "Content after deletion: $(pwd)"
            ls -la

      - name: Copy dist folder to remote host
        uses: appleboy/scp-action@v0.1.7
        with:
          host: ${{ secrets.REMOTE_HOST }}
          username: ${{ secrets.REMOTE_USERNAME }}
          key: ${{ secrets.REMOTE_KEY_ED25519 }}
          port: ${{ secrets.REMOTE_PORT }}
          source: 'dist/'
          target: '/home/ubuntu/traefik-proxy/apps/nmc-nginx-with-volume/website'
          # remove /dist path segment
          strip_components: 1

Example: deployment with rsync

Now we modify the existing Bash script and Github Actions workflow by replacing scp with rsync, while keeping the rest of the code identical.

Bash script

Most of the script remains the same. However, since we use rsync --delete, we can omit the step that deletes the previous deployment. In fact, the initial SSH call is no longer necessary, but we will keep it for debugging and transparency.

Another option worth mentioning is --info=progress2, which is very convenient in a live terminal session because it displays the current transfer progress in a concise way. This provides reassurance that the network connection is active and the transfer is progressing.

https://github.com/nemanjam/nemanjam.github.io/blob/main/scripts/deploy-nginx.sh

#!/bin/bash

LOCAL_PATH="./dist"
# REMOTE_PATH="~/traefik-proxy/apps/nmc-nginx-with-volume/website"
# REMOTE_HOST="arm1"

REMOTE_PATH=$1
REMOTE_HOST=$2

# Check if all arguments are provided
if [[ -z "$REMOTE_PATH" || -z "$REMOTE_HOST" ]]; then
  echo "Incorrect args, usage: $0 <remote_path> <remote_host>"
  exit 1
fi

# Navigate to the website folder on the remote server and clear contents of the website folder
ssh $REMOTE_HOST "cd $REMOTE_PATH && \
                  echo 'Listing files before clearing:' && \
                  echo 'List before clearing:' && \
                  ls && \
                  echo 'Count before clearing:' && \
                  ls -l | grep -v ^l | wc -l && \

                  # Only possible to skip with rsync --delete

                  # echo 'Clearing contents of the folder...' && \
                  # rm -rf * && \
                  # echo 'List after clearing:' && \
                  # ls && \
                  # echo 'Count after clearing:' && \
                  # find . -type f | wc -l && \

                  echo 'Copying new contents...'"

# Using rsync, fastest, resumable, deletes without clearing, lot faster with reusing unchanged files (--delete)
rsync -az --delete --info=stats2,progress2 $LOCAL_PATH/ $REMOTE_HOST:$REMOTE_PATH

# List all files after copying
ssh $REMOTE_HOST "cd $REMOTE_PATH && \
                  echo 'List after copying:' && \
                  ls && \
                  echo 'Count after copying:' && \
                  find . -type f | wc -l"

Github Actions

The workflow implements the same logic using the Burnett01/rsync-deployments action. Since this is not a live terminal session, --info=stats2 is sufficient for logging.

Unless you are actively debugging, avoid using the rsync -v flag, as overly verbose logs reduce readability.

https://github.com/nemanjam/nemanjam.github.io/blob/main/.github/workflows/default__deploy-nginx-rsync.yml

name: Deploy Nginx rsync

on:
  push:
    branches:
      - 'main'
    tags:
      - 'v[0-9]+.[0-9]+.[0-9]+'
  pull_request:
    branches:
      - 'disabled-main'
  workflow_dispatch:

env:
  SITE_URL: 'https://nemanjamitic.com'
  PLAUSIBLE_SCRIPT_URL: 'https://plausible.arm1.nemanjamitic.com/js/script.js'
  PLAUSIBLE_DOMAIN: 'nemanjamitic.com'

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          fetch-depth: 1

      - name: Print commit id, message and tag
        run: |
          git show -s --format='%h %s'
          echo "github.ref -> ${{ github.ref }}"

      - name: Set up Node.js and pnpm
        uses: actions/setup-node@v4
        with:
          node-version: 24.13.0
          registry-url: 'https://registry.npmjs.org'

      - name: Install pnpm
        uses: pnpm/action-setup@v4
        with:
          version: 10.30.1

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      - name: Build nemanjamiticcom
        run: pnpm build

      - name: Deploy dist via rsync
        uses: burnett01/rsync-deployments@v8
        with:
          switches: -az --delete --info=stats2
          path: dist/
          remote_path: /home/ubuntu/traefik-proxy/apps/nmc-nginx-with-volume/website/
          remote_host: ${{ secrets.REMOTE_HOST }}
          remote_user: ${{ secrets.REMOTE_USERNAME }}
          remote_port: ${{ secrets.REMOTE_PORT }}
          remote_key: ${{ secrets.REMOTE_KEY_ED25519 }}

Performance comparison

For Bash script measurements, I used my local network to deploy to a Raspberry Pi server. I used 1 Gbps Ethernet and 5 GHz, 433 Mbps WiFi 5. For Github Actions workflows, I used the standard Github runners available on the free plan. For each case, I took a few measurements to eliminate random anomalies. I didn’t aim for statistical accuracy.

For deployment, I used this very static Astro website you are currently reading. Its build artifacts consist of 1320 files totaling 347 MB (it contains a number of images).

Results discussion

Let’s comment on the results, starting from the worst option:

• scp has the worst performance in every case (Ethernet (9.6 s), WiFi (188 s), Github Actions (43 s)). The WiFi result is especially bad (188 seconds). I don’t have an exact explanation, but the WiFi connection probably doesn’t handle a large number of files well.
• tar + SSH has decent performance (Ethernet (4.1 s), WiFi (16.6 s), Github Actions (32 s)), considering that it clears the destination and transfers all files every time. Interestingly, on Ethernet it even performs 2× better (4.1 s) than rsync (with synchronization enabled) (8.8 s). I explain this by the fact that hashing and comparing files in rsync can cost more than the file transfer itself on a stable, wired Ethernet connection.
• rsync (cleared) (delete the destination and transfer everything each time) is on par with tar + SSH (Ethernet (4.6 s), WiFi (15.1 s), Github Actions (29 s)). This makes sense because those two methods are basically doing the same thing.
• rsync (synchronization enabled) overall has the best performance (Ethernet (8.8 s), WiFi (14.6 s), Github Actions (10 s)), with the exception of Ethernet, which I already explained (hashing and file comparison can cost more than network transfer). The Github Actions result (10 s) is especially important, since CI is the most common way to deploy apps in practice. It also creates around 14× less network traffic (24 MB compared to 347 MB).

Meaning, they rank in the following order (from best to worst):

1. rsync
2. rsync (cleared) and tar + SSH (equally fast)
3. scp (worst in every scenario)

Key takeaway: In Github Actions, rsync saves 43 - 10 = 33 seconds on each run compared to scp, which is a significant improvement.

Deployment process and Amdahl’s law

Transferring files is just one of the steps within the deployment process. It is not even the most dominant one. If we look at the times for each step in the Github Actions default__deploy-nginx-rsync.yml workflow, we can see the following:

Set up job                                    2s
Build burnett01/rsync-deployments@v8          9s
Checkout code                                18s
Print commit id, message and tag              0s
Set up Node.js and pnpm                       5s
Install pnpm                                  1s
Install dependencies                          6s
Build nemanjamiticcom                     2m 25s
Deploy dist via rsync                        10s
Post Install pnpm                             0s
Post Set up Node.js and pnpm                  0s
Post Checkout code                            0s
Complete job                                  0s

Deploy dist via rsync is third on the list with 10 seconds. Checkout code is second with 18 seconds. That step already has the fetch-depth: 1 optimization; the repository simply has a large file size. The app build step Build nemanjamiticcom obviously takes the most time and has the greatest potential for optimizing performance and saving time. Although obvious, this fact is also formally articulated by Amdahl’s law, which states:

The overall performance improvement gained by optimizing a single part of a system is limited by the fraction of time that the improved part is actually used.

However, the app’s build step is also the most complex to optimize. It spans the app code implementation, build configuration, and caching on both Vite and Github Actions levels. Naturally, it is largely app-dependent and more challenging to generalize.

If I look at the Astro build log, I can see this:

/_astro/snow1.DTiId6LS_Z2cIRXL.webp (reused cache entry) (+2ms) (1044/1101)

This image, snow1.DTiId6LS_Z2cIRXL.webp, has the exact same name in each build and is cached and reused, which drastically improves performance.

On the other hand, in the build log I can also see:

λ src/pages/api/open-graph/[...route].png.ts
  ├─ /api/open-graph/blog/2026-01-03-nextjs-server-actions-fastapi-openapi.png (+1.42s) 

This is an Open Graph image generated using a Satori HTML template, and it is regenerated from scratch on each build. I can see two problems with this:

1. Generating gradient colors in src/utils/gradients.ts uses Math.random(), which makes the generation non-deterministic. Instead, the gradient should use a pseudo-random, deterministic approach, for example by hashing the page title string.
2. The image snow1.DTiId6LS_Z2cIRXL.webp is originally placed inside the src directory, which registers it as an Astro asset. As a result, Astro handles compression, naming, and caching during the build process. This is not the case with the src/pages/api/open-graph/[...route].png.ts static route and the Satori template; additional configuration would be required to enable caching.

Anyway, that is a separate topic for a completely different article. In this one, we focus on the file transfer step, which can be optimized with minimal effort - simply by replacing a single command.

Completed code

• Repository: https://github.com/nemanjam/nemanjam.github.io

The relevant files:

git clone git@github.com:nemanjam/nemanjam.github.io.git

# Bash
scripts/deploy-nginx.sh

# Github Actions
.github/workflows/default__deploy-nginx-scp.yml
.github/workflows/default__deploy-nginx-rsync.yml

Conclusion

You might think, “This is a pretty long and verbose article for something that could be explained in two sentences” and you would probably be right. However, besides the main rsync vs scp point, I wanted to provide a drop-in script and workflow that you can reuse with minimal changes, just adjust the environment variables, build command, and deployment paths.

Additionally, real-world measurements help provide a realistic sense of how significant the performance improvements can be.

What methods do you use to optimize the deployment process in your projects? Let me know in the comments.

References

• Rsync repository https://github.com/RsyncProject/rsync
• Rsync manual, options https://download.samba.org/pub/rsync/rsync.1#OPTION_SUMMARY
• Rsync Github Action https://github.com/Burnett01/rsync-deployments
• SSH Github Action https://github.com/appleboy/ssh-action
• SCP Github Action https://github.com/appleboy/scp-action
• Amdahl’s law https://en.wikipedia.org/wiki/Amdahl%27s_law

This article focuses specifically on deploying static websites to Vercel. In a previous article https://nemanjamitic.com/blog/2026-02-22-vercel-deploy-fastapi-nextjs, we covered in detail how to deploy a full-stack application using the Vercel CLI from a local development environment. This time, we will use the same CLI inside a Github Actions runner to automate redeploying a static website on every push, for example, after adding a new blog article in markdown.

As an example, we will deploy the same blog website you are currently reading. The site itself is a statically built Astro application.

Vercel Github integration vs Github Actions

Vercel supports deployments through a Github integration (documented here: https://vercel.com/docs/git/vercel-for-github). You provide Vercel with your Github repository URL and read access, and Vercel automatically redeploys your application on every push. If you prefer not to grant Vercel access to your source code or Github repository, or if you want more control over the deployment process, you can instead use Github Actions, the approach described in this article.

Vercel configuration files

As with any Vercel deployment, you need to provide Vercel with additional information about the project’s build process, such as the framework, build command, and output directory, as well as which files should be included or ignored during deployment.

Before adding any configuration files, go to your Vercel dashboard, create a new project, give it a name, and set all required environment variables.

vercel.json

The contents of the vercel.json file are mostly self-explanatory. We specify the astro framework, and the build command and output directory match those used in the local development environment. With this configuration, Vercel knows exactly how to build the application.

https://github.com/nemanjam/nemanjam.github.io/blob/main/vercel.json

{
  "framework": "astro",
  "buildCommand": "pnpm build",
  "outputDirectory": "dist",
  "cleanUrls": true,
  "trailingSlash": false
}

.vercelignore

For performance reasons, it is important to avoid uploading files that are not used during the build and deployment process, such as dependencies, .env* files, documentation, or Docker-related configuration. The .vercelignore file is used to exclude these unnecessary files. Additionally, on the free tier, your deployment must stay below the 250 MB size limit.

https://github.com/nemanjam/nemanjam.github.io/blob/main/.vercelignore

# Node / package managers
node_modules
.pnpm-store
.npm
.yarn

# ! Needed for commit info
# Vercel omits it by default, now way to upload it
# .git
# .gitignore

# Local env files
.env
.env.*
!.env.*example

# Logs
npm-debug.log*
yarn-debug.log*
yarn-error.log*

# Docker & tooling
docker/
scripts/

# Documentation & notes
docs/

# OS / editor junk
.DS_Store
.idea
.vscode

# Astro build cache
.astro/*
# Keep types if build needs them
!.astro/types.d.ts

# Github
.github/

The exact contents of this file depend on your specific project. To ensure you have excluded all unnecessary paths, go to your Vercel dashboard and navigate to My Project -> My Deployment -> Source, where you can clearly see exactly which files are uploaded.

Github Actions workflow

Once again, go to your Vercel dashboard and create an access token in your account settings. Add this token as the VERCEL_TOKEN Github repository secret. Then, in your Vercel project settings, copy your user (organization) ID and project ID and add them as the VERCEL_ORG_ID and VERCEL_PROJECT_ID Github repository secrets.

With this setup, Github is aware of your Vercel project, and NOT the other way around. Vercel only receives the compiled application artifacts and has no access to your Github repository or source code.

https://github.com/nemanjam/nemanjam.github.io/blob/main/.github/workflows/vercel__deploy-manual.yml

name: Deploy to Vercel manually

# Docs example: https://vercel.com/kb/guide/how-can-i-use-github-actions-with-vercel

on:
  push:
    branches:
      - 'main'
    tags:
      - 'v[0-9]+.[0-9]+.[0-9]+'

  pull_request:
    branches:
      - 'disabled-main'

  workflow_dispatch:

permissions:
  contents: read

env:
  # Project vars
  # Redundant, vercel pull will define them
  # SITE_URL: 'https://nemanjam.vercel.app'
  # PLAUSIBLE_DOMAIN: 'nemanjamitic.com'
  # PLAUSIBLE_SCRIPT_URL: 'https://plausible.arm1.nemanjamitic.com/js/script.js'

  # Vercel vars
  VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }} # user id
  VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}

jobs:
  deploy-vercel:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          fetch-depth: 1

      - name: Print commit id and message
        run: |
          git show -s --format='%h %s'
          echo "github.ref -> ${{ github.ref }}"

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 24.13.0
          registry-url: 'https://registry.npmjs.org'

      - name: Install pnpm
        uses: pnpm/action-setup@v4
        with:
          version: 10.30.1

      - name: Install Vercel CLI
        run: pnpm add -g vercel

      - name: Pull Vercel production environment variables
        run: vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN }}

      - name: Build project using Vercel
        run: vercel build --prod --token=${{ secrets.VERCEL_TOKEN }}

      - name: Deploy prebuilt project to Vercel
        run: vercel deploy --prebuilt --prod --token=${{ secrets.VERCEL_TOKEN }}

Repository secrets

Vercel’s official tutorial already does a good job of explaining the basics and provides a solid starting workflow file: https://vercel.com/kb/guide/how-can-i-use-github-actions-with-vercel. In this article, we will focus on a specific use case: deploying a static website.

Let’s start by explaining the Github repository secrets used in this workflow:

• VERCEL_TOKEN - an access token that the Github Actions runner uses to authenticate with Vercel and create a deployment
• VERCEL_ORG_ID - a Github user or organization ID that identifies who owns the deployment
• VERCEL_PROJECT_ID - identifies the Vercel project being deployed

The VERCEL_ORG_ID and VERCEL_PROJECT_ID values are passed as environment variables and are defined at the workflow level, making them available to all jobs. The VERCEL_TOKEN is passed to individual commands as a command-line argument.

Set up Node.js and Vercel CLI

The first part of the workflow is standard and straightforward. We simply check out the repository (fetch-depth: 1 to fetch only the latest commit for speed), then install Node.js, pnpm, and the Vercel CLI. These steps set up the prerequisites needed to build and deploy the project in the following steps.

Environment variables

Here we are referring to your project’s environment variables. Since we are deploying a fully static website, all environment variables are strictly build-time variables, as explained here: https://nemanjamitic.com/blog/2025-12-21-static-website-runtime-environment-variables. The Vercel target environment does not need to define any variables because they are inlined during the build, immutable, and ignored afterward. This also means the build artifacts are specific to the environment they were built for.

Although variables in the target environment are ignored at runtime, it is still a good practice to define them in the Vercel dashboard and use Vercel as the single source of truth for your deployment. This allows you to easily pull them into the Github Actions runner using: vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN }}

The --environment=production flag selects the production environment. To deploy to preview environments, you can create a separate workflow .yml file triggered by feature branches (any branch other than main) and use vercel pull with the --environment=preview option to fetch the corresponding variables.

on:
  push:
    branches-ignore:
      - main

Note: You can define your project’s environment variables using the env: key at the workflow or job level, but this is generally not recommended. Doing so will lead to conflicts with variables pulled via vercel pull and issues with overriding priority, unless you are confident in managing them. Relying exclusively on variables from vercel pull ensures clarity and simplicity.

Building and deploying

At this point, we are ready to build the project using: vercel build --prod --token=${{ secrets.VERCEL_TOKEN }}. This command generates the application artifacts in the output folder specified in vercel.json, all within the Github Actions runner. After that, the Vercel CLI copies the framework’s output folder (defined in vercel.json) inside the .vercel/output folder, creating a deployment-ready package that can be uploaded directly to Vercel.

The final step is to upload the deployment-ready package inside the .vercel/output folder to Vercel using: vercel deploy --prebuilt --prod --token=${{ secrets.VERCEL_TOKEN }}. The --prebuilt option tells Vercel to skip the build step since the application has already been built in the Github Actions runner.

That’s it. Add the shown vercel.json, .vercelignore, and .github/workflows/vercel__deploy-manual.yml files to your repository, then run git push to trigger the workflow. Once it completes, you can view your website at <your-project-name>.vercel.app.

Completed code

• Repository: https://github.com/nemanjam/nemanjam.github.io
• Demo: https://nemanjam.vercel.app

The relevant files:

git clone git@github.com:nemanjam/nemanjam.github.io.git

# Files
.github/workflows/vercel__deploy-manual.yml
vercel.json
.vercelignore

.dockerignore
.gitignore

# Vercel configuration and workflow in a clear diff
https://github.com/nemanjam/nemanjam.github.io/commit/c0d6c6739b3215a6841a463115ec5242ea76e492

Conclusion

CI/CD workflows are the standard way to handle deployments, and deploying to Vercel is no exception. By combining Github Actions with the Vercel CLI, you can implement a fully automated deployment pipeline with just a few lines of configuration.

This approach gives you complete control over the build and deployment process while keeping your source code private and your security model explicit. Once in place, deployments become predictable, repeatable, and hands-off.

How do you automate deployments to Vercel in your projects? Let me know in the comments.

References

• Github Actions with Vercel, Vercel official tutorial https://vercel.com/kb/guide/how-can-i-use-github-actions-with-vercel
• Astro on Vercel, Vercel docs https://vercel.com/docs/frameworks/frontend/astro
• Github integration, Vercel docs https://vercel.com/docs/git/vercel-for-github
• vercel deploy --prebuilt option, Vercel docs https://vercel.com/docs/cli/deploy#prebuilt

import { IMAGE_SIZES } from ’../../../../constants/image’; import DeploymentDiagramImage from ’../../../../content/post/2026/02-22-vercel-deploy-fastapi-nextjs/_images/vercel-fastapi-nextjs.png’; import FrontendScreenshotImage from ’../../../../content/post/2026/02-22-vercel-deploy-fastapi-nextjs/_images/frontend-screenshot-1200x630.png’; import BackendScreenshotImage from ’../../../../content/post/2026/02-22-vercel-deploy-fastapi-nextjs/_images/backend-screenshot-1200x630.png’; import VercelButtonWizardScreenshotImage from ’../../../../content/post/2026/02-22-vercel-deploy-fastapi-nextjs/_images/vercel-button-wizard-screenshot.png’;

Introduction

This article is a practical guide that presents a single, proven approach for deploying a FastAPI and Next.js application on Vercel. It is not intended to be a comprehensive, in depth overview of all Vercel features or deployment options. The main idea is to show how to host demo apps on Vercel for free.

Python is one of the runtimes with first-class support on Vercel, as stated in the documentation: https://vercel.com/docs/functions/runtimes. Additionally, FastAPI is an officially supported backend framework and is documented here: https://vercel.com/docs/frameworks/backend/fastapi.

Naturally, Next.js is developed by Vercel and has full, native support on the platform. Given all of this, deploying a full-stack FastAPI and Next.js application on Vercel is entirely viable, and we can confidently proceed with the configuration and deployment.

Project structure prerequisites

<Image {…IMAGE_SIZES.FIXED.MDX_MD} src={DeploymentDiagramImage} alt=“Deployment diagram” />

There are certain constraints on how a FastAPI and Next.js project must be structured and configured in order to be deployable on Vercel. When deploying with Docker, we typically use separate containers for the backend and frontend, since a container is designed to run a single process. Similarly, on Vercel we will use two separate deployments, one for the backend and one for the frontend, and connect them using the SITE_URL and API_URL environment variables.

In general, a full-stack application should be designed without making assumptions about the values of SITE_URL and API_URL, allowing the backend and frontend to be hosted independently on any arbitrary domains.

This is especially important for authentication and cookies, since the frontend and backend will use different *.vercel.app domains. Because these domains are included in the public suffix list (https://publicsuffix.org/list), cookie behavior cannot be fully controlled across them.

One effective solution is to enforce a clean separation of concerns: use FastAPI for authentication logic, and rely on Next.js API routes or server actions for setting and unsetting cookies. I covered this approach in detail in a previous article: https://nemanjamitic.com/blog/2026-02-07-github-login-fastapi-nextjs#architecture-overview.

Note: If your project originally hosts the backend and frontend on the same domain and relies on a reverse proxy such as Nginx or Traefik for routing, you will need to reconfigure this setup, as Vercel does not provide that level of routing control.

Configuration

Vercel offers two basic ways to deploy a project: 1. using the CLI to deploy from a local machine, and 2. deploying from a repository URL, such as Github or Gitlab. There are also several variations of these approaches, including the “Vercel button” which launches a setup wizard from a repository URL, and Github Actions, where the CLI is used inside a workflow runner.

In this tutorial, we will use the CLI approach and deploy both the backend and frontend directly from our local development machine.

We will begin by installing the Vercel CLI globally on our local machine and then logging in with our Vercel account.

# Install Vercel CLI
pnpm install -g vercel

# Log in to Vercel
vercel login

Configuring the FastAPI backend

vercel.json

First, we need to expose a FastAPI entry point in a way that can be consumed by a Vercel serverless function.

https://github.com/nemanjam/full-stack-fastapi-template-nextjs/blob/vercel-deploy/backend/app/api/index.py

# Required by vercel.json to locate the FastAPI `app` instance.
# `# noqa: F401` prevents formatters from removing this import.

from app.main import app  # noqa: F401

Then we can use it in vercel.json to define the build path for the serverless function and the root request handler for HTTP requests.

https://github.com/nemanjam/full-stack-fastapi-template-nextjs/blob/vercel-deploy/backend/vercel.json

{
  "builds": [
    {
      "src": "app/api/index.py",
      "use": "@vercel/python"
    }
  ],
  "routes": [
    {
      "src": "/(.*)",
      "dest": "app/api/index.py"
    }
  ]
}

.vercelignore

Next, we need to define the backend’s root project directory and specify which files should be included or excluded from the serverless function. This step is important to avoid unnecessary bloat, as it affects both performance and the 250 MB size limit for Vercel functions on the free plan. By default, the root project directory is the folder where you run the vercel CLI command, though you can override it during the deployment prompt.

The .vercelignore file is used to exclude files from being uploaded during deployment. It should be placed inside the root project directory. If you already have a properly configured .dockerignore, these two files are basically the same. Below is my .vercelignore configuration:

https://github.com/nemanjam/full-stack-fastapi-template-nextjs/blob/vercel-deploy/backend/.vercelignore

# Python
.venv/
__pycache__/
.ruff_cache/
.mypy_cache/
.pytest_cache/
app.egg-info
*.pyc

# Tests
.coverage
htmlcov

Dockerfile*

# ignore database
!data/database
data/database/*
!data/database/.gitkeep

You can also verify and debug any redundant files in the Vercel dashboard under My Project -> My Deployment -> Source. I highly recommend performing this check to ensure that no unnecessary bloat is included in the serverless function.

Additionally, add the backend/.vercel/ directory to your .gitignore file. This directory contains local Vercel configuration and should not be committed to Git.

# Local Vercel configuration
.vercel/

Environment variables

Your application already relies on certain environment variables that are configured in a specific way. However, their names and formats may not fully align with the predefined variables available in the Vercel environment, so some adaptation is usually required. In my case, this involved the following changes:

1. I had an ENVIRONMENT variable that needed to be derived from the predefined VERCEL_ENV variable and then reassigned using a Pydantic model validator.
2. For the database configuration, I originally used five separate variables: POSTGRES_SERVER, POSTGRES_PORT, POSTGRES_USER, POSTGRES_PASSWORD, and POSTGRES_DB. These were replaced with a single DATABASE_URL variable, which is exposed by Neon by default. This value can then be piped into a SQLALCHEMY_DATABASE_URI computed property.

https://github.com/nemanjam/full-stack-fastapi-template-nextjs/blob/vercel-deploy/backend/app/core/config.py

# Vercel default vars
VERCEL_ENV: str | None = None

# ...

# for Vercel and Neon
DATABASE_URL: PostgresDsn | None = None

# Local / Docker fallback
POSTGRES_SERVER: str | None = None
POSTGRES_PORT: int = 5432
POSTGRES_USER: str | None = None
POSTGRES_PASSWORD: str | None = None
POSTGRES_DB: str | None = None

# ...

@computed_field  # type: ignore[prop-decorator]
@property
def SQLALCHEMY_DATABASE_URI(self) -> PostgresDsn:
    # Vercel + Neon
    if self.DATABASE_URL:
        database_url = str(self.DATABASE_URL)
        # Force SQLAlchemy to use psycopg v3 on Vercel (Neon provides postgresql:// by default)
        if database_url.startswith("postgresql://"):
            database_url = database_url.replace(
                "postgresql://", "postgresql+psycopg://"
            )
        return database_url

    # Local / Docker
    if not all(
        [
            self.POSTGRES_SERVER,
            self.POSTGRES_USER,
            self.POSTGRES_PASSWORD,
            self.POSTGRES_DB,
        ]
    ):
        raise ValueError(
            "Either DATABASE_URL (Vercel/Neon) or POSTGRES_* variables must be set"
        )

    return MultiHostUrl.build(
        scheme="postgresql+psycopg",
        username=self.POSTGRES_USER,
        password=self.POSTGRES_PASSWORD,
        host=self.POSTGRES_SERVER,
        port=self.POSTGRES_PORT,
        path=self.POSTGRES_DB,
    )

# ...

@model_validator(mode="after")
def resolve_environment(self) -> Self:
    if self.VERCEL_ENV == "production":
        self.ENVIRONMENT = "production"
    elif self.VERCEL_ENV == "preview":
        self.ENVIRONMENT = "staging"
    # else: keep whatever ENVIRONMENT was set from OS/.env
    return self

As already noted, SITE_URL is a particularly important variable, as it is the primary way to inform the backend about the domain on which the frontend is hosted. It is used throughout the backend for CORS whitelisting, redirects, constructing absolute URLs, etc.

You may not have this value available during the initial backend deployment. In that case, you can temporarily set a placeholder value to satisfy Pydantic validation. Once the actual frontend URL is known, update the variable via the Vercel dashboard or CLI and redeploy the application for the change to take effect.

Below is the full list of required and optional environment variables used by this backend application:

https://github.com/nemanjam/full-stack-fastapi-template-nextjs/blob/vercel-deploy/.env.vercel.example

# ------------ Required vars --------------

# Frontend url
# Used by the backend to generate links in emails to the frontend
SITE_URL=my-frontend-url.vercel.app

# Auth
JWT_SECRET_KEY=my-secret
SESSION_SECRET_KEY=my-secret

# Superuser email and password
FIRST_SUPERUSER=admin@example.com
FIRST_SUPERUSER_PASSWORD=password

# Postgres database, e.g. Neon
# Format: postgresql://<username>:<password>@<host>/<database>?<query>
# Neon example: postgresql://neondb_owner:npg_someHash@ep-solitary-moon-some-hash-pooler.c-3.us-east-1.aws.neon.tech/neondb?sslmode=require
DATABASE_URL=

# ------------ Optional vars --------------

# Used in email templates and OpenAPI docs
PROJECT_NAME="Full stack FastAPI template Next.js"

# Whitelisted frontend urls
# SITE_URL is included by default
BACKEND_CORS_ORIGINS="http://localhost,https://localhost,http://localhost:3000,https://localhost:3000,http://localhost:3001,https://localhost:3001,https://my-frontend-url.vercel.app"

# Environment: local, staging, production
# If omitted defaults to VERCEL_ENV
ENVIRONMENT=production

# If omitted defaults to 7 days = 24 * 7 = 168 hours
ACCESS_TOKEN_EXPIRE_HOURS=168

# Github OAuth id and secret
# Only a single deployment (callback url) per Github app is possible
GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=

# Postgres database, e.g. Neon
# Supply either all POSTGRES_* variables or a single DATABASE_URL
# If both are defined DATABASE_URL has precedence
POSTGRES_SERVER=localhost
POSTGRES_PORT=5432
POSTGRES_DB=app
POSTGRES_USER=postgres
POSTGRES_PASSWORD=password

Database migrations and seed

At this point, the only remaining step is to obtain a valid DATABASE_URL that points to a migrated, seeded, and running database instance. You can use any cloud or self-hosted PostgreSQL instance, as long as it is accessible over the internet. In this case, we will use Neon, since it is an officially supported PostgreSQL integration on Vercel.

Create an account at https://neon.com, then create a new project and a new database. Next, connect the database to your Vercel project using the Neon integration and use the default production database branch. When the integration is added, Neon will automatically expose certain environment variables to your Vercel deployment, which you can customize in the Neon integration settings. The DATABASE_URL variable is exposed by default, and since we configured the backend to use it in the previous step, no further action is required at this stage.

At this point, the backend can connect to the database, but the database is still empty. We now need to run migrations to create the tables and seed the initial data.

Note: You might be tempted to automate database migrations and seeding (especially for demo apps) by running them on application startup. However, since Vercel is a serverless environment, there is no single, well-defined application start event (unlike a VPS or Docker-based setup). Instead, multiple instances can start independently, which would cause migrations and seeds to run multiple times in an unpredictable manner. This can lead to serious issues. For this reason, database migrations and initial seeding should be performed as a single, manual step.

We will use our local development environment, where the application is already fully installed and configured, to run the migrations and seed the data. In the local .env file, simply replace the local development database connection with the remote production database connection that is already used by the Vercel deployment.

Also, make sure to check out the vercel-deploy branch locally, as only that branch is configured to handle the DATABASE_URL variable correctly.

# Checkout vercel-deploy branch that has Vercel configuration (backend/vercel.json, backend/.vercelignore, backend/app/api/index.py, modified backend/app/core/config.py)
git checkout vercel-deploy

# Comment out local Postgres database
# POSTGRES_SERVER=localhost
# POSTGRES_PORT=5433
# POSTGRES_DB=app
# POSTGRES_USER=postgres
# POSTGRES_PASSWORD=password

# Neon database url example used on Vercel:
DATABASE_URL=postgresql://neondb_owner:npg_some-slug@ep-rough-cherry-some-slug-pooler.c-3.us-east-1.aws.neon.tech/neondb?sslmode=require

Now we can run the migrations and seed the Neon remote database. Make sure that all backend dependencies are installed and that your Python virtual environment is activated. Be patient and allow the command to complete, as this process can take a few minutes.

# From /backend
cd ./backend

# Create virtual environment
uv venv

# Activate the environment
source .venv/bin/activate

# Install dependencies
uv sync

# Migration and seed scripts need activated venv and Python dependencies

# Await db, run migrations and seed (must have .env)
# With a remote Neon database, this command can take a few minutes to complete
# Be patient and do not interrupt it
bash scripts/prestart.sh

Open the Neon dashboard and verify that the user and item tables have been created and populated with the seed data. At this point, the backend is fully configured and ready to be deployed using the Vercel CLI.

Deploying backend from terminal

First, install the vercel CLI and log in with your Vercel account. Then navigate to the backend directory and start the deployment wizard by running the vercel --prod command. The wizard will prompt you to:

• Link an existing Vercel project or create and name a new one (this determines the app’s public URL)
• Select the project root directory - choose the current directory (./)
• Set environment variables - this step can be skipped for now
• Modify the build configuration - select “No”

# Install Vercel CLI
pnpm install -g vercel

# Log in to Vercel
vercel login

# Navigate to the backend folder
cd backend

# Deploy for the first time (production)
# Fill prompts for name, root directory `./` (vercel.json dir)
vercel --prod

# Add required environment variables (production) (after the wizard completes)
echo "Full stack FastAPI template Next.js" | vercel env add PROJECT_NAME production
echo "https://my-frontend-url.vercel.app" | vercel env add SITE_URL production
echo "my-secret" | vercel env add JWT_SECRET_KEY production
echo "my-secret" | vercel env add SESSION_SECRET_KEY production
echo "admin@example.com" | vercel env add FIRST_SUPERUSER production
echo "password" | vercel env add FIRST_SUPERUSER_PASSWORD production
echo "postgresql://user:pass@host/db" | vercel env add DATABASE_URL production
# Set more optional variables...

# List existing environment variables
vercel env ls

# Redeploy after changes
vercel --prod  # production

# After deploy, the CLI outputs the URL
# Example: https://api-full-stack-fastapi-template-nextjs-my-slug.vercel.app

# Debug deployment
vercel inspect https://api-full-stack-fastapi-template-nextjs-my-slug.vercel.app --json

Treat the initial deployment as disposable. At this stage, the frontend is likely not deployed yet, which means the SITE_URL value is not available. You can temporarily set a placeholder URL that satisfies Pydantic validation. Once the frontend is deployed, update SITE_URL with the actual value using the CLI (as shown earlier) or via the Vercel dashboard (Project -> Settings -> Environment Variables).

The same approach applies to other environment variables, such as GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET. After updating any environment variable, you must redeploy the project for the changes to take effect.

# Update (remove and add) an existing env var SITE_URL
vercel env rm SITE_URL production --yes
echo "https://my-new-frontend-url.vercel.app" | vercel env add SITE_URL production

Once the deployment wizard completes successfully, you can verify the result by accessing the FastAPI backend at the URL printed in the terminal, for example: https://api-full-stack-fastapi-template-nextjs-my-slug.vercel.app/docs.

This will display the OpenAPI UI. The exact URL depends on how you named the project. You can view all associated URLs in the Vercel dashboard under the deployment settings.

<Image {…IMAGE_SIZES.FIXED.MDX_MD} src={BackendScreenshotImage} alt=“OpenAPI screenshot” />

Configuring the Next.js frontend

Deploying the Next.js application is much simpler, as it requires fewer environment variables and no database. However, there are still a few details to keep in mind, which we will cover here.

vercel.json

We use a vercel.json file to specify the framework, install and build commands, and the output directory. These settings mirror the local development environment and are pretty self-explanatory.

https://github.com/nemanjam/full-stack-fastapi-template-nextjs/blob/vercel-deploy/frontend/apps/web/vercel.json

{
  "framework": "nextjs",
  "installCommand": "pnpm install",
  "buildCommand": "pnpm turbo run build --filter=web",
  "outputDirectory": ".next"
}

Note that our Next.js application uses a monorepo setup with Turbo, which has a few implications:

• The vercel.json file is NOT placed at the monorepo root (frontend/). Instead, it lives in the Next.js application directory at frontend/apps/web/vercel.json. Despite this, the Vercel project root directory IS the monorepo root (frontend/), since all packages and source files must be uploaded in order to build the application successfully. This is the correct approach for deploying monorepo projects to Vercel.
• The .vercelignore file should also be placed in the monorepo root directory (frontend/).

.vercelignore

As with the backend, we need to ignore all unused local files during deployment to prevent unnecessary uploads, performance degradation, and excess bloat, and to stay below the 250 MB limit for a serverless function. Once again, it is a good idea to verify that nothing was missed by checking My Project -> My Deployment -> Source in the Vercel dashboard.

https://github.com/nemanjam/full-stack-fastapi-template-nextjs/blob/vercel-deploy/frontend/.vercelignore

# Node.js
**/node_modules/
**/.next/
**/.turbo/
**/dist/

# Ignore all env files, env vars are passed into container explicitly
**/.env*

# Tests
**/test-results/
**/playwright-report/
**/blob-report/
**/playwright/.cache/

Similarly, add the frontend/.vercel/ directory to your frontend .gitignore file. This directory contains local Vercel configuration and should not be committed to Git.

https://github.com/nemanjam/full-stack-fastapi-template-nextjs/blob/vercel-deploy/frontend/.gitignore

# Local Vercel configuration
.vercel/

Environment variables

The frontend uses far fewer environment variables, only two in fact: API_URL, which points to the backend URL, and SITE_URL, which represents the frontend’s own URL. The value of SITE_URL can be derived from the predefined VERCEL_PROJECT_PRODUCTION_URL variable exposed by Vercel.

https://github.com/nemanjam/full-stack-fastapi-template-nextjs/blob/vercel-deploy/frontend/apps/web/.env.vercel.example

# ------------ Required vars --------------

# Backend url
API_URL=https://my-backend-url.vercel.app

# ------------ Optional vars --------------

# Frontend url
# If omitted defaults to https:// + VERCEL_PROJECT_PRODUCTION_URL
SITE_URL=https://my-frontend-url.vercel.app

With this in mind, we need to include VERCEL_PROJECT_PRODUCTION_URL in the Next.js environment variable handling logic.

Set it as a fallback value in the next-public-env schema.

https://github.com/nemanjam/full-stack-fastapi-template-nextjs/blob/vercel-deploy/frontend/apps/web/src/config/process-env.ts

export const { getPublicEnv, PublicEnv } = createPublicEnv(
  {
    NODE_ENV: process.env.NODE_ENV,
    SITE_URL: process.env.SITE_URL || `https://${process.env.VERCEL_PROJECT_PRODUCTION_URL}`,
    API_URL: process.env.API_URL,
  },
  { schema: (z) => getProcessEnvSchemaProps(z) }

Include it in the process.env type.

https://github.com/nemanjam/full-stack-fastapi-template-nextjs/blob/vercel-deploy/frontend/apps/web/src/env.d.ts

declare namespace NodeJS {
  interface ProcessEnv {
    readonly NODE_ENV: 'development' | 'production' | 'test';
    readonly SITE_URL: string;
    readonly API_URL: string;
    readonly VERCEL_PROJECT_PRODUCTION_URL: string;
  }
}

Notify Turborepo.

https://github.com/nemanjam/full-stack-fastapi-template-nextjs/blob/vercel-deploy/frontend/turbo.json

{
  "$schema": "https://turbo.build/schema.json",
  "ui": "tui",
  "globalEnv": ["NODE_ENV", "SITE_URL", "API_URL", "NEXT_RUNTIME", "VERCEL_PROJECT_PRODUCTION_URL"],
  
  // ...

}

That’s it. Our Next.js frontend is ready for deployment.

Deploying frontend from terminal

Deploying the frontend is very similar to deploying the backend, with the main difference being the selection of the project root directory, since we are deploying a monorepo. Navigate to the frontend directory and start the deployment wizard by running the vercel --prod command. The wizard will prompt you to:

• Link an existing Vercel project or create and name a new one (this determines the app’s public URL)
• Select the project root directory - choose the Next.js app directory (./apps/web/)
• Set environment variables - this step can be skipped for now
• Modify the build configuration - select “No”

# Install Vercel CLI
pnpm install -g vercel

# Log in to Vercel
vercel login

# Navigate to the frontend folder
cd frontend

# Deploy for the first time (production)
# Fill prompts for name, root directory `./apps/web/` (vercel.json dir)
vercel --prod

# Set required environment variables (production)
echo "https://api-full-stack-fastapi-template-nextjs-my-slug.vercel.app" | vercel env add API_URL production
# Set more optional variables...

# List existing environment variables
vercel env ls

# Redeploy after changes
vercel --prod  # production

# After deploy, the CLI outputs the URL
# Example: https://full-stack-fastapi-template-nextjs-my-slug.vercel.app

# Debug deployment
vercel inspect https://full-stack-fastapi-template-nextjs-my-slug.vercel.app --json

Make sure to set the environment variables API_URL and SITE_URL (optional), either through the Vercel dashboard (Project -> Settings -> Environment Variables) or via the CLI. If SITE_URL is not set, it will fall back to the predefined VERCEL_PROJECT_PRODUCTION_URL variable, as explained earlier.

Remember to redeploy the project whenever you update environment variables to apply the changes.

# Update (remove and add) an existing env vars API_URL and SITE_URL

vercel env rm API_URL production --yes
echo "https://api-full-stack-fastapi-template-nextjs-my-slug.vercel.app" | vercel env add API_URL production

vercel env rm SITE_URL production --yes
echo "https://full-stack-fastapi-template-nextjs-my-slug.vercel.app" | vercel env add ITE_UR production

If everything is configured correctly, your full-stack FastAPI and Next.js application should now be fully deployed and functional at the URL displayed in the terminal: https://full-stack-fastapi-template-nextjs-my-slug.vercel.app

The exact URL will depend on the name you chose for the project. Congratulations!

<Image {…IMAGE_SIZES.FIXED.MDX_MD} src={FrontendScreenshotImage} alt=“Frontend screenshot” />

Vercel button

In addition to the CLI, Vercel also allows deploying a project by simply specifying the repository URL. Naturally, the repository must be properly prepared and configured beforehand. One variation of this method is the “Vercel Deploy” button, a URL-encoded href link that points to Vercel and includes query parameters for the repository URL, environment variables, integrations, and other necessary configuration details. When clicked, it launches a setup wizard to complete any remaining deployment configuration.

Vercel also provides a utility form to generate these buttons conveniently: https://vercel.com/docs/deploy-button. The “Vercel Deploy” button can be embedded in markdown or HTML pages, allowing visitors to deploy a live demo of your project quickly and effortlessly.

With this in mind, we can define a single “Vercel Deploy” button to deploy both the backend and frontend of our FastAPI and Next.js project. It will clone a single Github repository and create two separate Vercel projects. We can then include the button’s Markdown in the project’s README.md file.

The button below specifies URLs (repository, demo, images, etc.) for this particular example, you can adjust them to match your own URLs.

Single monorepo Vercel button

This is fairly self-explanatory, but let’s clarify the query parameters for completeness:

• repository-url - points to the Github repository and the vercel-deploy branch.
• repository-name - the name of the cloned repository.
• root-directories - specifies the backend (backend) and frontend root directories (frontend/apps/web).
• monorepo - indicates that a single Git repository contains multiple Vercel projects.
• totalProjects - number of Vercel projects to create.

Additional parameters include:

• project-names - the names the backend and frontend Vercel projects.
• demo-* - information and URLs displayed in the wizard for demo purposes.

The products parameter is particularly important, as it activates the Neon integration in the wizard to provision a new PostgreSQL database.

# URL for the "Vercel Deploy" button's href attribute

https://vercel.com/new/clone
?repository-url=https://github.com/nemanjam/full-stack-fastapi-template-nextjs/tree/vercel-deploy
&root-directories=frontend/apps/web,backend
&repository-name=full-stack-fastapi-template-with-next-js
&monorepo=1
&totalProjects=2
&project-names=full-stack-fastapi-frontend,full-stack-fastapi-backend
&demo-description=Build full-stack apps with Next.js and FastAPI.
&demo-image=https://github.com/nemanjam/full-stack-fastapi-template-nextjs/raw/main/docs/screenshots/frontend-screenshot-1200x630.png
&demo-title=Full stack FastAPI template with Next.js
&demo-url=https://full-stack-fastapi-template-nextjs.vercel.app
&skippable-integrations=1
&products=[
  {
    "type": "integration",
    "integrationSlug": "neon",
    "productSlug": "neon",
    "protocol": "storage"
  }
]

Once the URL is constructed, it should be URL-encoded and then embedded in the markdown (or HTML) as shown below.

<!-- Markdown for the button -->

[![Deploy backend to Vercel](https://vercel.com/button)](urlencoded-url-from-above)

The button and wizard will clone a single GitHub repository and create and deploy two separate backend and frontend Vercel projects. The deployments are not functional at this point. The wizard will not set any required environment variables for either the backend or frontend projects. Users will need to set the appropriate environment variables themselves in the Vercel dashboard.

The wizard will also create an integration that provisions an unassigned, blank Neon database. Users will then need to assign the integration to the backend project and run migrations and seed the database manually, as described in the previous section: Database migrations and seed.

After clicking the “Vercel Deploy” button, the user will be taken to a form wizard, as shown below.

<Image {…IMAGE_SIZES.FIXED.MDX_MD} src={VercelButtonWizardScreenshotImage} alt=“Vercel button wizard” />

Note: You can also use two separate “Vercel Deploy” buttons to clone the backend and frontend as two Github repositories (and deploy them as two Vercel projects). This approach allows you to include the list of environment variables and their default values (env, envDefaults, and envDescription parameters) in the button’s URL.

You can see examples of such buttons at the following links: vercel-button-backend.md, vercel-button-frontend.md

Completed code and demo

• Repository and branch: https://github.com/nemanjam/full-stack-fastapi-template-nextjs/tree/vercel-deploy
• Demo frontend: https://full-stack-fastapi-template-nextjs.vercel.app
• Demo backend: https://api-full-stack-fastapi-template-nextjs.vercel.app/docs

The relevant branch vercel-deploy and files:

git clone git@github.com:nemanjam/full-stack-fastapi-template-nextjs.git

# Checkout the vercel-deploy branch
git checkout vercel-deploy

# Backend
backend/vercel.json
backend/.vercelignore

backend/app/api/index.py
backend/app/core/config.py

.env.vercel.example
docs/notes/vercel-deployment-backend.md

# Frontend
frontend/apps/web/vercel.json
frontend/.vercelignore

frontend/apps/web/src/config/process-env.ts
frontend/apps/web/src/env.d.ts
frontend/turbo.json

frontend/apps/web/.env.vercel.example
docs/notes/vercel-deployment-frontend.md

# Compare branches in a clear diff
https://github.com/nemanjam/full-stack-fastapi-template-nextjs/compare/vercel-deploy?expand=1

# Compare specific commits in a clear diff
https://github.com/nemanjam/full-stack-fastapi-template-nextjs/compare/45c840d48cba2aeab07e0a66f8245110b852571e...e5fa4b4af3c19c8c2c584fe437b7298f9e342083

Conclusion

Vercel is a quite viable option for hosting full-stack FastAPI and Next.js demo projects for free. It works well when the project is designed around serverless constraints. Keeping the backend and frontend as separate deployments, using environment variables consistently, and handling database migrations manually results in a setup that is simple, predictable, and reliable on the free tier.

This guide focused on one practical approach that is easy to reproduce and debug. With the provided repository and Vercel Deploy buttons, you can use this setup as a solid baseline for demos, prototypes, or small production projects.

Have you done something similar yourself and used a different approach? Leave a comment below, I’m happy to hear your opinions.

References

• Vercel docs, supported runtimes https://vercel.com/docs/functions/runtimes
• Vercel docs, supported backend frameworks https://vercel.com/docs/frameworks/backend/fastapi
• Vercel docs, deploying Next.js https://vercel.com/docs/frameworks/full-stack/nextjs
• Vercel docs, deploy button form https://vercel.com/docs/deploy-button
• Neon integration example template https://github.com/neondatabase/vercel-marketplace-neon

import { IMAGE_SIZES } from ’../../../../constants/image’; import GithubLoginArchitectureImage from ’../../../../content/post/2026/02-07-github-login-fastapi-nextjs/_images/github-login-architecture-16-9.png’; import OAuth2FlowDiagramImage from ’../../../../content/post/2026/02-07-github-login-fastapi-nextjs/_images/oauth2-diagram.png’;

Introduction

In this article, we will show how to implement Github login in a FastAPI and Next.js application. We use Github in this particular case, but the same approach applies to any OAuth provider, you only need to adjust the FastAPI redirect and callback endpoints. Since this is a Next.js app using server components, we will store the session in an HttpOnly cookie. We will dig into implementation details such as domains, cookies, redirects, and overall structuring to achieve a clean, maintainable, and robust solution.

OAuth flow reminder

OAuth2 flow sequential diagram: (Source gist)

<Image {…IMAGE_SIZES.FIXED.MDX_MD} src={OAuth2FlowDiagramImage} alt=“OAuth2 flow sequential diagram” />

Let’s begin with a quick reminder of how OAuth works in very simplified terms. OAuth is built around the principle of a trusted middleman: both we (our app) and the user know who Github is (the authorization server) and trust it. This means we can use Github to identify the user and obtain their information. For the user, this means Github vouches for our app’s identity and legitimacy, clearly showing what information the app will access and at what level, so the user can give informed consent. Of course, there are many more implementation details, but this is enough for a high-level overview.

For our app, this practically means we need to register it with Github, obtain the app’s client ID and client secret, and then, in the backend, use an OAuth client library to implement two endpoints:

1. An endpoint that redirects the user to Github, where they can give consent.
2. A callback endpoint where Github redirects the user back to us, passing an authorization code that the auth library can exchange for an access token, which is then used to call Github APIs and obtain additional information about the user.

Additionally, within the callback endpoint we store the user’s information (email, OAuth ID, name, avatar, etc.) in the database and use the autogenerated database user ID to generate a JWT access token, in the same way we do for a regular email/password authenticated user.

In this way, we achieve a unified interface for authenticating users, regardless of whether they log in with Github or via email/password.

Architecture overview

Architecture diagram:

<Image {…IMAGE_SIZES.FIXED.MDX_MD} src={GithubLoginArchitectureImage} alt=“Github login architecture diagram” />

The one obvious and constant assumption is that we will use a FastAPI backend and a Next.js frontend. When it comes to authorization, this leaves additional room for deciding how we structure the logic and separate concerns. There is more than one way to do this, and some approaches can be fragile and hard to maintain, which is exactly what we want to avoid.

Let’s go straight to the point and explain the optimal approach that we will use, and then briefly touch on some suboptimal alternatives and the kinds of problems they introduce.

• Since we use Next.js and server components, we will store the session in an HttpOnly cookie so we can have private, server-side rendered pages. This means localStorage is not used for storing authentication state.

• The frontend and backend are separate applications, which means they run as separate Node.js and Python processes and are deployed as separate containers (reminder: Docker containers are meant to run a single process per container). This also applies to the domains on which the frontend and backend run. Ideally, we want complete freedom to use any unrelated domains for both, without making assumptions about subdomains, prefixes, or shared domain structure.

• Cookies are tightly coupled to domains: a browser will accept and store a cookie only if it is set by a server running on the correct domain. The fact that Next.js provides API functionality is very fortunate, because those endpoints run on the same domain as the rest of the Next.js app (pages) and can set cookies for that exact domain. This removes the need to deal with cross-domain cookies, which are often complex and fragile.

• Cookies are tied to a domain and are impractical for passing arguments via HTTP responses. Cookies are meant for storing data, not for transmitting it. Consequently, for passing the access_token and expires values, we will use the response body (for server actions) and URL query parameters (for the OAuth redirect). Response bodies and URL query parameters are domain-independent and are designed for passing data between HTTP requests.

• Separation of concerns on the backend: FastAPI will contain all backend logic, including authorization. This means it will implement both OAuth endpoints (the redirect and callback endpoints). Next.js will handle cookie setting and unsetting logic: via server actions for email/password login, and via Next.js API routes for Github login. As a reminder, a server action is essentially a POST endpoint under the hood and can set or unset cookies.

• The OAuth callback endpoint in FastAPI needs to initiate an uninterrupted redirect chain composed of two steps (FastAPI and Next.js API): Github -> FastAPI callback redirect -> Next.js API redirect -> Next.js home page. During this process, the access_token and expires values need to be passed as query parameters appended to the URL. Redirects are mandatory because the entire flow is driven by the browser, and we do not want the user’s browser to just land on a raw API response, but rather on the website’s home page as a successfully logged-in user.

Suboptimal approaches and their problems

There is some ambiguity caused by the redundancy of options, which can lead to suboptimal solutions if we do not think clearly enough. Let’s discuss some of them:

• Since we have two backend-capable frameworks, we might be tempted to move a significant part of the authorization logic into Next.js APIs, for example, implementing the OAuth redirect endpoint, the callback endpoint, or even the email/password authentication endpoints there. This would introduce several serious problems, including unnecessary coupling of two backends to the same database and schema, backend deployment being split across two containers that must stay in strict sync, fragmented configuration and secrets management, violation of the “single source of truth” principle, potential read/write race conditions, and increased debugging and logging complexity.

  To prevent all of this, we enforce a clear separation of concerns: FastAPI acts as a complete, standalone backend, while Next.js APIs (and server actions) are responsible only for setting and unsetting cookies. Since Next.js runs on the frontend domain, this approach drastically simplifies and hardens cookie handling.

• Another pitfall is relying on cross-domain cookies by making assumptions about the domains used by the frontend and backend. For example, we might assume SITE_URL=https://my-website.com for the frontend and API_URL=https://api.my-website.com for the backend. In that case, the backend could tweak cookie properties such as SameSite=None and Domain=.my-website.com to get the browser to accept and store the cookie.

  This introduces additional complexity and fragility into the authentication flow and deployment reliability, along with a number of problems and limitations. Some of them include a major mismatch between email/password login (where the cookie is set directly via a server action) and OAuth login, the inability to host the frontend and backend on completely different, unrelated domains (which is a legitimate requirement), and the inability to host the backend on a PaaS that uses domains included in the public suffix list (https://publicsuffix.org/list/), such as vercel.app.

  Once again, this is solved by letting the Next.js API (and server actions) handle setting and unsetting cookies.

Implementation

That was a lot of text but still no code. On the other hand when we have clear mental model and worked out plan implementation is straight forward.

Create OAuth app on Github

Like with any OAuth provider we need to register our app on Github and obtain client id and client secret. One Github specific is that you can have set only one redirect URL per app, so if you want multiple deployments you will need to create a separate app for each of them.

It’s a straight forward process, go to your Github profile and open the following menus: Github (top-right avatar) -> Settings -> Developer settings (bottom of the left sidebar) -> OAuth Apps -> New OAuth App. Fill in your app info, including redirect URL where you should set the URL of your FastAPI callback endpoint, e.g. https://api.my-website.com/api/v1/auth/github/callback.

Then copy Client ID and Client secret and set inside the backend .env file.

# ...

GITHUB_CLIENT_ID=Ov23liasdxhfaOJasdf12
GITHUB_CLIENT_SECRET=c9ad7bc12977515fed61409492abe169212345

# ...

Instantiate OAuth client

We need to install OAuth client library, we will use authlib/authlib.

# Activate venv
source .venv/bin/activate

# Install authlib
poetry add authlib

Then we can instantiate OAuth client:

GITHUB_OAUTH_CONFIG = {
    "name": "github",
    "client_id": settings.GITHUB_CLIENT_ID,
    "client_secret": settings.GITHUB_CLIENT_SECRET,
    "access_token_url": "https://github.com/login/oauth/access_token",
    "authorize_url": "https://github.com/login/oauth/authorize",
    "api_base_url": "https://api.github.com/",
    "client_kwargs": {"scope": "user:email"},
}


def create_oauth() -> OAuth:
    oauth = OAuth()
    oauth.register(**GITHUB_OAUTH_CONFIG)
    return oauth


oauth = create_oauth()

Define OAuth endpoints in FastAPI

We can then use the instantiated OAuth client to implement the OAuth redirect and callback endpoints.

The redirect endpoint is quite simple, almost trivial. When the user hits this endpoint, they are redirected to the Github login page, where they can give consent. The redirect_uri variable contains the absolute URL of our callback endpoint, which we define next.

@router.get("/login/github")
async def login_github(request: Request):
    """
    Redirect to Github login page
    Must initiate OAuth flow from backend
    """
    redirect_uri = request.url_for("auth_github_callback")  # matches function name

    # rewrite to https in production
    if is_prod:
        redirect_uri = redirect_uri.replace(scheme="https")

    return await security.oauth.github.authorize_redirect(request, redirect_uri)

Now we can define the callback endpoint, which is where Github sends the user after they have logged in on Github. This part is a bit more complex.

Github includes an authorization code as a URL parameter, which we use to obtain an OAuth access token. We then use this token to call two separate Github APIs: one to retrieve the user’s profile information (full name, username, and OAuth ID), and another to retrieve the user’s primary email address. Next, we find or create the user in our database. Finally, we use the user’s database ID to create a JWT token, in exactly the same way as we do for a regular email/password user.

Next, we calculate the expires value for the session cookie so that it matches the JWT access_token expiration. We then attach the access_token and expires values as query parameters to the redirect URL. The redirect URL is constructed as f"{settings.SITE_URL}/api/auth/set-cookie", pointing to a Next.js API endpoint (which we define next) that is responsible for actually setting the cookie. Finally, we redirect the user.

Once again, it is important to emphasize that the redirect is essential so the browser can follow the entire chain. We do not want the user to land on a raw API response, the home page is the final destination after a successful login.

@router.get("/auth/github/callback")
async def auth_github_callback(
    request: Request, session: SessionDep
) -> RedirectResponse:
    """
    Github OAuth callback, Github will call this endpoint
    """
    # Exchange code for access token
    token = await security.oauth.github.authorize_access_token(request)

    # Get user profile Github API
    user_info = await security.oauth.github.get("user", token=token)
    profile = user_info.json()

    # Get primary email Github API
    emails = await security.oauth.github.get("user/emails", token=token)
    primary_email = next((e["email"] for e in emails.json() if e["primary"]), None)

    logger.info(f"Primary Github email: {primary_email}")

    # Authenticate or create user
    user = crud.authenticate_github(
        session=session,
        primary_email=primary_email,
        profile=profile,
    )

    expires_delta = timedelta(hours=settings.ACCESS_TOKEN_EXPIRE_HOURS)

    access_token = security.create_access_token(user.id, expires_delta)

    # Absolute expiration timestamp (UTC)
    expires_at = datetime.now(timezone.utc) + expires_delta
    expires_timestamp = int(expires_at.timestamp())

    # Build redirect URL to Next.js cookie-setter
    base_url = f"{settings.SITE_URL}/api/auth/set-cookie"
    query = urlencode(
        {
            "access_token": access_token,
            "expires": expires_timestamp,
        }
    )
    redirect_url = f"{base_url}?{query}"

    response = RedirectResponse(url=redirect_url, status_code=302)

    return response

Note the fixed dict type Token used for passing cookie properties. It is important that this type is identical and shared between both OAuth and email/password flows, ensuring that they conform to the same interface.

class Token(SQLModel):
    access_token: str
    # Absolute Date, timestamp, sufficient
    expires: int

Set cookie - Next.js API endpoint

Now that we have identified the user on Github and created the JWT access_token, the only remaining step is to set the cookie. As mentioned earlier, in the OAuth flow this is done in a Next.js API endpoint.

Below is the complete endpoint implementation. As you can see, it is not too complicated. We simply parse the access_token and expires values from the URL query parameters, use them to construct the cookie, and attach the cookie to a redirect response that sends the user to the home page. This final step sets the cookie, and that’s it.

It’s also worth mentioning that if the query parameters are invalid, we redirect the user back to the login page.

Note that we construct the cookie as host-only (domain: undefined), meaning it is valid only for the frontend domain. This is perfectly fine and exactly what we want, since in a Next.js app both pages and APIs run on the same domain.

export const GET = async (request: Request): Promise<Response> => {
  const { SITE_URL, NODE_ENV } = getPublicEnv();
  const isProd = NODE_ENV === 'production';

  const url = new URL(request.url);

  const accessToken = url.searchParams.get('access_token');
  const expiresParam = url.searchParams.get('expires');

  const hasAllData = accessToken && expiresParam;
  if (!hasAllData) {
    const loginUrl = new URL(`${LOGIN}?error=missing_auth_token`, SITE_URL);
    return NextResponse.redirect(loginUrl, { status: 302 });
  }

  // Convert Unix timestamp (seconds) to a JS Date object
  const expiresDate = new Date(Number(expiresParam) * 1000);

  const redirectUrl = new URL(DASHBOARD, SITE_URL);
  const response = NextResponse.redirect(redirectUrl, { status: 302 });

  response.cookies.set({
    name: AUTH_COOKIE,

    // passed from backend
    value: accessToken,
    expires: expiresDate,

    // frontend-specific
    httpOnly: true,
    secure: isProd,

    // host-only
    path: '/',
    sameSite: 'lax',
    domain: undefined,
  });

  return response;
};

Set/unset cookie - Next.js server action

Although a server action is used to set the session cookie only for the email/password login, it is important to explain the complete authentication picture, show how both login flows conform to the same interface, and highlight some differences.

In contrast to the OAuth flow, which relies on redirects, the email/password login can simply call the FastAPI endpoint LoginService.loginAccessToken({ body }) and obtain the access_token and expires values from the response body to construct the cookie.

Once again, the cookie is host-only (domain: undefined) and included in the server action response. Under the hood, a server action is just a POST request, which effectively sets the cookie.

export const loginAction = async (
  _prevState: ApiResult,
  formData: FormData
): Promise<ApiResult> => {
  const { NODE_ENV } = getPublicEnv();

  const body = Object.fromEntries(formData) as BodyLoginLoginAccessToken;
  const apiResponse = await LoginService.loginAccessToken({ body });

  const { response: _, ...result } = apiResponse;

  const isSuccess = isSuccessApiResult(result);
  // UI will display backend error
  if (!isSuccess) return result;

  const { access_token, expires } = result.data;
  const isProd = NODE_ENV === 'production';

  // Convert Unix timestamp (seconds) to a JS Date object
  const expiresDate = new Date(Number(expires) * 1000);

  const cookieStore = await cookies();

  cookieStore.set({
    name: AUTH_COOKIE,
    // args
    value: access_token,
    expires: expiresDate,
    // local
    httpOnly: true,
    secure: isProd,
    // host-only for exact frontend domain
    path: '/',
    sameSite: 'lax',
    domain: undefined,
  });

  // success result is ignored, just for type
  return result;
};

Another server action is used for logout. It simply unsets the cookie and applies to both email/password and OAuth logins, since both rely on the same session cookie.

export const logoutAction = async (): Promise<void> => {
  const cookiesList = await cookies();
  cookiesList.delete(AUTH_COOKIE);

  redirect(LOGIN);
};

Differences between the email/password and OAuth flows

So what is different between the email/password and OAuth flows?

The OAuth flow is based on two consecutive redirects: FastAPI callback endpoint -> Next.js API set-cookie endpoint -> Home page. This is mandatory because the callback endpoint is the only thing Github provides us, and the access_token and expires values must be passed as query parameters attached to the redirect responses.

In contrast, the email/password flow is based on an HTML form and a server action, which follows a standard request/response pattern. This allows the access_token and expires values to be sent directly in the response body.

Completed code

• Repository: https://github.com/nemanjam/full-stack-fastapi-template-nextjs

The relevant files:

git clone git@github.com:nemanjam/full-stack-fastapi-template-nextjs.git
git checkout 45c840d48cba2aeab07e0a66f8245110b852571e

# Backend
backend/app/api/routes/login.py
backend/app/core/security.py
backend/app/crud.py
backend/app/models.py

# Frontend container (Next.js)
# API route
frontend/apps/web/src/app/api/auth/set-cookie/route.ts
# Server action
frontend/apps/web/src/actions/auth.ts

# Pull request with most of the code shown in a clear diff
https://github.com/nemanjam/full-stack-fastapi-template-nextjs/pull/4

Conclusion

Let’s conclude this article by summarizing the upsides and downsides of choosing to move the cookie-setting logic to Next.js server actions and APIs.

Upsides:

• The frontend and backend are fully independent. We can use any domains for both by simply setting the SITE_URL and API_URL environment variables.
• We can deploy to platforms like vercel.app without needing any additional modifications.
• We maintain a single, unified interface for both email/password and OAuth logins.
• The approach is applicable to any OAuth provider, not just Github. You only need to define the appropriate redirect and callback endpoints in FastAPI.

Downsides:

• Slightly increased complexity caused by moving the cookie-setting logic into Next.js server actions and APIs.
• The frontend container must include a Node.js runtime to support Next.js server actions and APIs. In practice, this is not much of a downside, since using SSR was already part of the plan.

Have you implemented something similar yourself? What approach did you choose? Let me know in the comments.

References

• Authlib FastAPI docs https://docs.authlib.org/en/latest/client/fastapi.html, blog article https://blog.authlib.org/2020/fastapi-google-login, example https://github.com/authlib/demo-oauth-client/tree/master/fastapi-google-login
• List of all known public suffixes https://publicsuffix.org/list/

import { IMAGE_SIZES } from ’../../../../constants/image’; import DeploymentDiagramImage from ’../../../../content/post/2026/01-03-nextjs-server-actions-fastapi-openapi/_images/deployment-diagram-16-8.png’ import SequentialDiagramImage from ’../../../../content/post/2026/01-03-nextjs-server-actions-fastapi-openapi/_images/sequential-diagram.png’

Introduction

In 2026, Next.js and server components are the industry standard for building server-side rendered React websites. Next.js comes with API routes by default for building backend endpoints, but for various reasons you may want to use a completely different programming language and a non-TypeScript backend. For example, FastAPI is known for its excellent integration with ML and AI libraries, which are typically implemented in Python.

Today we will show how to implement one critical part of every full-stack app: data fetching and data mutations using Next.js and FastAPI. There is more than one way to do this, but we will aim to choose and implement the best one.

We will not start completely from scratch, but instead reuse https://github.com/fastapi/full-stack-fastapi-template as a starting point. It already provides a solid foundation, especially on the backend, where we will only change session storage from localStorage to an HttpOnly cookie. In contrast, we will replace most of the frontend code by switching from TanStack Router, React Query, and Chakra to Next.js 16, ShadcnUI, and Tailwind CSS v4.

The problem statement and requirements

What is the real challenge here? Modern React 19 and Next.js 16 provide new, advanced features and a standardized workflow not only for fetching data into components but also for managing state. These span both the server and the client, and we should aim to fully leverage them.

So the real goal is this: we want to use a non-TypeScript backend while at the same time preserving the well-established server components model for data fetching and the server actions model for data mutations, with the same level of type safety and state management we would have when using Next.js API endpoints.

Architecture overview

Visual representation of the architecture we will build in this tutorial.

Deployment diagram:

<Image {…IMAGE_SIZES.FIXED.MDX_MD} src={DeploymentDiagramImage} alt=“Deployment diagram, client JavaScript, Next.js server and FastAPI server” />

Sequential diagram:

<Image {…IMAGE_SIZES.FIXED.MDX_MD} src={SequentialDiagramImage} alt=“Sequential diagram, client JavaScript, Next.js server and FastAPI server” />

Modify the backend to use HttpOnly cookie auth

Server-side rendering and server components are central features of modern Next.js and React. The original starter stores the session in the browser’s localStorage, which prevents us from having server-side rendered private pages and components. We will modify this to store the session in an HttpOnly cookie instead, which we can access and read in server components.

In the original repository, there is already a pull request, Replace plaintext auth tokens with HttpOnly cookies #1606, that implements this. We will reuse it and adapt it to our needs. Let’s highlight the most important parts of this code and discuss them.

First, let’s create utilities to set and unset the auth cookie in API responses. Note the signature of the set_auth_cookie method: set_auth_cookie(subject, expires_delta, response). We pass in the subject (typically a user.id) and the token’s expiration, as well as a response argument of the base class type Response so that this utility can be applied to any specific response subclass. The create_access_token() method itself remains unchanged; the token is created the same way for both localStorage and cookies.

backend/app/core/security.py

def set_auth_cookie(
    subject: str | Any, expires_delta: timedelta, response: Response
) -> Response:
    # Cookie expiration and JWT expiration match
    # Note: cookie expiration must be in seconds
    expires_in_seconds = int(expires_delta.total_seconds())
    access_token = create_access_token(subject, expires_delta)

    # Dev defaults
    samesite = "lax"
    domain = None

    # Prod overrides
    if is_prod:
        samesite = "none"
        # Note: important for cross-site cookies in prod to succeed
        # api-site.rpi.example.com and site.rpi.example.com
        parsed = urlparse(settings.SITE_URL)
        domain = parsed.hostname  # full domain

        # if it has subdomains whitelist cookie for "1 level less" subdomain, rpi.example.com
        host_segments = domain.split(".")
        if len(host_segments) > 2:
            domain = ".".join(host_segments[1:])  # remove the first segment (head)

    logger.info(f"domain: {domain}")

    response.set_cookie(
        key=settings.AUTH_COOKIE,
        value=access_token,
        httponly=True,
        max_age=expires_in_seconds,
        expires=expires_in_seconds,
        samesite=samesite,
        secure=is_prod,
        domain=domain,
    )
    return response

The core idea is straightforward: create a token, assign it to the cookie value, and attach the cookie to the response object.

There is some added cross-site cookie complexity specific to my use case, which you may not necessarily need to replicate, but let’s explain it for the sake of clarity.

Cross site cookie configuration

In general, in practice, the frontend and backend often don’t share the same domain, and you need to account for this because cookies are tied to a domain. For example, if the frontend is on my-website.com and the backend is on api.my-website.com, the backend must set domain = "my-website.com" and samesite = "none" for the browser to accept and store the cookie.

On my server, I use an additional Traefik TCP router that treats a dot . as a special delimiter character, which prevents it from correctly routing infinite-depth subdomains. As a result, I had to use a dash - instead for my backend domain.

# frontend url
https://full-stack-fastapi-template-nextjs.arm1.nemanjamitic.com

# backend url
https://api-full-stack-fastapi-template-nextjs.arm1.nemanjamitic.com

The additional cookie domain logic essentially does the following: if the frontend is on a subdomain, it sets the cookie for the parent domain (one level up). For example, in this specific case, arm1.nemanjamitic.com.

That’s enough for this digression, I just wanted to emphasize that you must carefully adjust the domain property of a cross-site cookie depending on the URLs where you host your frontend and backend. Otherwise, the browser will reject the cookie, and authentication will fail.

Similarly, we use this code to unset the auth cookie. We simply return a JSONResponse containing an expired cookie with the same key. It can be improved, but it will suffice for now.

backend/app/core/security.py

def delete_auth_cookie() -> JSONResponse:
    response = JSONResponse(content={"message": "Logout successful"})
    response.delete_cookie(
        key=settings.AUTH_COOKIE,
        path="/",
        domain=None,
        httponly=True,
        samesite="lax",
        secure=is_prod,
    )
    return response

Login / logout endpoints

Now it’s time to make use of these utilities to log in and log out a user.

For login, we first verify that the user has provided a valid email and password. If the credentials are correct, we use the user.id to generate an access token, set it as the cookie value, and include the cookie in the response using the previously mentioned security.set_auth_cookie() utility.

backend/app/api/routes/login.py

@router.post("/login/access-token")
def login_access_token(
    session: SessionDep, form_data: Annotated[OAuth2PasswordRequestForm, Depends()]
) -> JSONResponse:
    """
    OAuth2-compatible token login: get an access token for future requests (sent in an HTTP-only cookie)
    """
    user = crud.authenticate(
        session=session, email=form_data.username, password=form_data.password
    )
    if not user:
        raise HTTPException(status_code=400, detail="Incorrect email or password")
    elif not user.is_active:
        raise HTTPException(status_code=400, detail="Inactive user")

    access_token_expires = timedelta(hours=settings.ACCESS_TOKEN_EXPIRE_HOURS)
    response = JSONResponse(content={"message": "Login successful"})

    return security.set_auth_cookie(user.id, access_token_expires, response)

For logout, we simply use the security.delete_auth_cookie() utility to unset the cookie from the user’s browser.

Note: we are implementing this endpoint for the sake of completeness in the FastAPI backend. In our particular setup, however, we will use the Next.js server to clear the auth cookie.

backend/app/api/routes/login.py

@router.post("/logout", dependencies=[Depends(get_current_user)])
def logout() -> JSONResponse:
    """
    Delete the HTTP-only cookie during logout
    """
    return security.delete_auth_cookie()

Protect endpoints with auth

After implementing login and logout, we can use them to protect specific API endpoints by identifying the user from the request and checking whether they have sufficient privileges to access a resource or perform an action.

We will use FastAPI’s dependency injection to centralize the logic for obtaining the auth cookie with CookieDep and for identifying the user who sent the cookie with CurrentUser. The get_current_user() method checks for the existence of the cookie, decodes and verifies the validity of the access token from the cookie, and finally uses the user.id from the token’s subject to query the user from the database.

backend/app/api/deps.py

cookie_scheme = APIKeyCookie(name=settings.AUTH_COOKIE)

CookieDep = Annotated[str, Depends(cookie_scheme)]


def get_current_user(session: SessionDep, cookie: CookieDep) -> User:
    if not cookie:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Not authenticated",
        )

    try:
        payload = jwt.decode(
            cookie, settings.JWT_SECRET_KEY, algorithms=[security.ALGORITHM]
        )
        token_data = TokenPayload(**payload)
    except (InvalidTokenError, ValidationError):
        raise HTTPException(
            status_code=status.HTTP_403_FORBIDDEN,
            detail="Could not validate credentials",
        )

    user = session.get(User, token_data.sub)
    if not user:
        raise HTTPException(status_code=404, detail="User not found")
    if not user.is_active:
        raise HTTPException(status_code=400, detail="Inactive user")

    return user

CurrentUser = Annotated[User, Depends(get_current_user)]

Now, any function or route in FastAPI can make use of the CurrentUser dependency to identify the user simply by including it as a typed argument. Below is a simple /me endpoint for illustration.

backend/app/api/routes/users.py

@router.get("/me", response_model=UserPublic)
def read_user_me(current_user: CurrentUser) -> Any:
    """
    Get current user.
    """
    return current_user

With this HttpOnly cookie setup, authentication on the backend is complete. Essentially, we didn’t change much, we only moved the access token from the JSON body of the response to the cookie header.

Generate and configure OpenAPI client

Now that we have moved the session from localStorage to an HttpOnly cookie, we can identify the user in server components on the Next.js server. An important and obvious note worth repeating: HttpOnly cookies are accessible only on the Next.js server, not in the client-side JavaScript running in the browser.

Since our setup involves Next.js client -> Next.js server -> FastAPI server, we need to handle cookie transmission accordingly. We will continue using the @hey-api/openapi-ts package from the original template, but for our Next.js app, we will use the @hey-api/client-next client and configure it to handle the auth cookie properly.

Here is the configuration for generating the OpenAPI client:

frontend/apps/web/openapi-ts.config.ts

const config: HeyApiConfig = defineConfig({
  input: './openapi.json',
  output: {
    format: 'prettier',
    lint: 'eslint',
    path: './src/client',
    importFileExtension: null,
  },
  exportSchemas: true, // backend models types
  plugins: [
    // Note: order matters
    {
      name: '@hey-api/typescript',
      enums: 'javascript', // const objects instead of enums
    },
    '@hey-api/schemas', // default json, req.body, '{"username":"abc","password":"123"}'
    {
      name: '@hey-api/sdk',
      asClass: true, // UsersService.readUserMe(), 'true' doesn't allow tree-shaking
      classNameBuilder: '{{name}}Service', // class Users -> UsersService
      // @ts-expect-error @hey-api/openapi-ts doesn't export types
      methodNameBuilder, // usersReadUserMe -> readUserMe
    },
    {
      name: '@hey-api/client-next',
      // relative from src/client/ folder
      runtimeConfigPath: '../lib/hey-api', // sets API_URL, auth...
    },
  ],
});

The important parts are: we choose the Next.js client @hey-api/client-next, control the SDK method names using the methodNameBuilder callback, and specify the path for the generated client runtime configuration with runtimeConfigPath.

Runtime client configuration

There are several ways to set runtime configuration for the generated client. We will use the runtimeConfigPath field to specify the path to the configuration file, as this is the recommended approach according to the docs: https://heyapi.dev/openapi-ts/clients/next-js#runtime-api.

The auth cookie is originally stored in the browser and is included in client requests by default. An important note is that the cookie in these requests is valid only for the frontend domain (Next.js server) and not for the backend domain. If you try calling the FastAPI backend using this cookie, you will get a 403 Forbidden HTTP error. That’s why requests from client code need to be proxied through a Next.js API endpoint to the FastAPI backend.

In contrast, HTTP requests made from the Next.js server do not include the cookie automatically at all, so we need to forward it explicitly.

We handle both of these requirements in a base runtime configuration at the SDK instance level in a single place, so we don’t have to repeat this logic for every specific call.

Here is the code:

frontend/apps/web/src/lib/hey-api.ts

const { CLIENT_PROXY } = ROUTES.API;

/** Runtime config. Runs and imported both on server and in browser. */
export const createClientConfig: CreateClientConfig = (config) => {
  const { API_URL } = getPublicEnv();

  return {
    ...config,
    baseUrl: API_URL,
    credentials: 'include',
    fetch: isServer() ? serverFetch : clientFetch,
  };
};

const serverFetch: typeof fetch = async (input, init = {}) => {
  // Note: Dynamic import to avoid bundling 'next/headers' on client
  const { cookies } = await import('next/headers');

  const cookieStore = await cookies();
  const cookieHeader = cookieStore
    .getAll()
    .map((c) => `${c.name}=${c.value}`)
    .join('; ');

  // Note: must append auth_cookie like this or content-type header will break in server actions
  const headers = new Headers(init.headers);
  headers.append('Cookie', cookieHeader);

  // test skeletons styling
  // await waitMs(3000);

  const response = fetch(input, { ...init, headers });

  return response;
};

/** Client-side fetch: forwards requests to api/client-proxy/[...path]/route.ts */
const clientFetch: typeof fetch = async (input, init = {}) => {
  const { API_URL } = getPublicEnv() as { API_URL: string };

  // hey-api sends absolute URL
  const url: string = typeof input === 'string' ? input : input.toString();

  // Normalize to relative URL
  // API_URL.length + 1 - removes leading slash, API_URL guaranteed not to have trailing slash
  const relativeUrl = url.startsWith(API_URL) ? url.slice(API_URL.length + 1) : url;

  // Build the proxy URL relative to Next.js API
  const proxyUrl = `${CLIENT_PROXY}${relativeUrl}`;

  const headers = new Headers(init.headers);

  return fetch(proxyUrl, { ...init, headers, credentials: 'include' });
};