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:

```bash
# 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:

```bash
hugo build
```

This generates the static files in the `public/` directory.

### 2. Set Environment Variables

Set the FTPS credentials as environment variables:

```bash
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:

```bash
./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:

```bash
# 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):

```bash
# .env
FTPS_PASSWORD=your-password
```

Then source it before deployment:

```bash
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:

```bash
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:

```yaml
- 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