markusgraf_ch/DEPLOYMENT.md

Deployment Guide

This guide explains how to deploy the Hugo-built static site to the production server at www.markusgraf.ch.

Prerequisites

Before deploying, ensure you have:

1. Built the site: Run hugo build to generate the public/ directory
2. lftp installed: The deployment script requires the lftp command-line tool
3. FTPS credentials: You need the FTPS username and password for the server

Installing lftp

If lftp is not installed on your system:

# Ubuntu/Debian
sudo apt-get install lftp

# macOS
brew install lftp

# Fedora
sudo dnf install lftp

Deployment Process

1. Build the Site

First, build the Hugo site:

hugo build

This generates the static files in the public/ directory.

2. Set Environment Variables

Set the FTPS credentials as environment variables:

export FTPS_USER='gurix'
export FTPS_PASSWORD='your-password-here'

Important: Never commit passwords to version control. Credentials should only be stored as environment variables.

3. Run the Deployment Script

Execute the deployment script:

./scripts/deploy.sh

The script will:

• Check that all prerequisites are met
• Connect to www.markusgraf.ch via FTPS
• Upload all files from public/ to httpsdocs/ on the server
• Display progress and completion status

Complete Example

Here's the full workflow:

# Build the site
hugo build

# Set credentials (only needed once per session)
export FTPS_USER='gurix'
export FTPS_PASSWORD='your-password'

# Deploy
./scripts/deploy.sh

Server Configuration

The deployment script uses the following configuration:

• Server: www.markusgraf.ch
• Protocol: FTPS (FTP over SSL/TLS)
• Username: gurix
• Target Directory: httpsdocs/
• Source Directory: public/

Security Notes

Credential Management

• Never hardcode passwords in scripts or configuration files
• Never commit passwords to version control
• Use environment variables to pass credentials securely
• The deployment script never displays passwords in its output

Optional: Using .env Files

For convenience, you can create a .env file (which is ignored by git):

# .env
FTPS_PASSWORD=your-password

Then source it before deployment:

source .env
./scripts/deploy.sh

Troubleshooting

Error: "Directory 'public' does not exist"

Cause: The Hugo site hasn't been built yet.

Solution: Run hugo build before deploying.

Error: "lftp is not installed"

Cause: The lftp tool is not available on your system.

Solution: Install lftp using the instructions above.

Error: "FTPS_PASSWORD environment variable is not set"

Cause: The password environment variable hasn't been set.

Solution: Run export FTPS_PASSWORD='your-password' before deploying.

Connection Failures

Cause: Network issues or incorrect credentials.

Solutions:

• Verify your internet connection
• Check that the password is correct
• Ensure the server (www.markusgraf.ch) is accessible
• Verify firewall settings aren't blocking FTPS (port 21)

Partial Upload Failures

Cause: Network interruption during upload.

Solution: Simply run the deployment script again. The mirror command will resume and complete the upload.

Advanced Usage

Testing Without Deploying

To test the script without actually uploading files, you can modify the deploy() function temporarily to use the --dry-run flag:

mirror --reverse --delete --verbose --parallel=3 --dry-run $SOURCE_DIR $TARGET_DIR;

Deployment from CI/CD

For automated deployments from CI/CD pipelines:

1. Store FTPS_PASSWORD as a secret in your CI/CD system
2. Ensure the CI/CD environment has lftp installed
3. Run the deployment script after successful builds

Example GitHub Actions workflow snippet:

- name: Deploy to server
  env:
    FTPS_PASSWORD: ${{ secrets.FTPS_PASSWORD }}
  run: ./scripts/deploy.sh

Support

If you encounter issues not covered in this guide:

1. Check the server logs
2. Verify network connectivity to www.markusgraf.ch
3. Ensure the httpsdocs/ directory exists on the server
4. Contact your hosting provider for server-side issues