---
version: "1.0"
date: "2025-01-15"
author: "DWS Foldsite Team"
title: "Deployment Overview"
description: "Getting Foldsite running - from local development to production"
summary: "Learn how to deploy Foldsite in various environments: local development, Docker containers, or production servers."
quick_tips:
  - "Start with local development for fastest iteration"
  - "Docker provides consistent environments across machines"
  - "Production deployment supports both dynamic and static modes"
---

# Deployment Overview

Foldsite is flexible in how you run it. Choose the deployment method that fits your needs:

## Deployment Options

### [Local Development](local-development.md)

**Best for:** Content creation, theme development, testing

Run Foldsite directly with Python for the fastest development cycle. Changes to content and templates appear immediately (no rebuild needed).

```bash
python main.py --config config.toml
```

**Pros:**
- Fastest iteration - see changes instantly
- Easy debugging with Python stack traces
- Full access to logs and error messages

**Cons:**
- Requires Python environment
- Manual dependency management
- Not suitable for production

**When to use:** Always use this during development. It's the fastest way to see your changes.

### [Docker Deployment](docker.md)

**Best for:** Consistent environments, easy deployment, testing production builds

Run Foldsite in a Docker container for isolated, reproducible deployments.

```bash
docker-compose up
```

**Pros:**
- Consistent across development and production
- Isolated dependencies
- Easy to share with team members
- Simplifies deployment to cloud platforms

**Cons:**
- Slight overhead from containerization
- Requires Docker knowledge
- Extra layer to debug

**When to use:** Use Docker when you need consistency across environments, or when deploying to platforms that support containers.

### [Production Deployment](production.md)

**Best for:** Public-facing websites, high-traffic sites, static hosting

Deploy Foldsite as either a dynamic Python server or export to static files.

**Dynamic Mode:**
```bash
gunicorn -w 4 -b 0.0.0.0:8081 main:app
```

**Static Export:**
```bash
# Generate static HTML files
python export.py --output ./dist
```

**Pros:**
- Optimized for production workloads
- Can use static hosting (cheap/free)
- Supports CDN caching
- Professional-grade performance

**Cons:**
- More complex setup
- Requires understanding of web servers
- Static mode requires rebuilds for updates

**When to use:** Use this for your live website once development is complete.

## Quick Comparison

| Method | Speed | Complexity | Best For |
|--------|-------|------------|----------|
| **Local Development** | ⚡⚡⚡ | ⭐ | Creating content and themes |
| **Docker** | ⚡⚡ | ⭐⭐ | Team collaboration, staging |
| **Production (Dynamic)** | ⚡⚡ | ⭐⭐⭐ | Live sites with frequent updates |
| **Production (Static)** | ⚡⚡⚡ | ⭐⭐⭐ | Live sites, maximum performance |

## Prerequisites

### For All Deployment Methods

1. **Git** (to clone the repository)
   ```bash
   git --version
   ```

2. **A text editor** (VS Code, Sublime, vim, etc.)

### For Local Development

1. **Python 3.10+**
   ```bash
   python3 --version
   ```

2. **pip** (Python package manager)
   ```bash
   pip --version
   ```

### For Docker Deployment

1. **Docker** and **Docker Compose**
   ```bash
   docker --version
   docker-compose --version
   ```

### For Production Deployment

Choose based on your hosting strategy:

- **Dynamic mode:** Python 3.10+, web server (nginx/apache)
- **Static mode:** Any web server or static host (GitHub Pages, Netlify, etc.)

## Getting the Source Code

All deployment methods start by getting Foldsite:

```bash
# Clone the repository
git clone https://github.com/DWSresearch/foldsite.git
cd foldsite

# Or download and extract the latest release
wget https://github.com/DWSresearch/foldsite/archive/main.zip
unzip main.zip
cd foldsite-main
```

## Configuration

Every deployment uses a `config.toml` file to specify paths and settings:

```toml
[paths]
content_dir = "/path/to/your/content"
templates_dir = "/path/to/your/templates"
styles_dir = "/path/to/your/styles"

[server]
listen_address = "0.0.0.0"
listen_port = 8081
admin_browser = false
admin_password = "change-me"
max_threads = 4
debug = false
access_log = true
```

**Important:** Adjust these paths before running Foldsite!

### Development Config Example

```toml
[paths]
content_dir = "./my-site/content"
templates_dir = "./my-site/templates"
styles_dir = "./my-site/styles"

[server]
listen_address = "127.0.0.1"  # Local only
listen_port = 8081
debug = true                   # Enable debug mode
access_log = true
```

### Production Config Example

```toml
[paths]
content_dir = "/var/www/site/content"
templates_dir = "/var/www/site/templates"
styles_dir = "/var/www/site/styles"

[server]
listen_address = "0.0.0.0"     # All interfaces
listen_port = 8081
debug = false                   # Disable debug mode
access_log = true
max_threads = 8                 # More workers for production
```

## Typical Deployment Workflow

### 1. Development Phase

Use **local development** for content creation and theme building:

```bash
# Edit content
vim content/my-post.md

# Run server
python main.py --config config.toml

# Visit http://localhost:8081
# See changes immediately
```

### 2. Testing Phase

Use **Docker** to test in a production-like environment:

```bash
# Build and run
docker-compose up

# Test on http://localhost:8081
# Verify everything works in container
```

### 3. Deployment Phase

Deploy to **production** using your preferred method:

```bash
# Option A: Dynamic server
gunicorn -w 4 main:app

# Option B: Static export
python export.py --output ./dist
rsync -avz ./dist/ user@server:/var/www/site/
```

## Common Scenarios

### Scenario: Personal Blog

**Best deployment:** Local development + static export to GitHub Pages

```bash
# Develop locally
python main.py --config config.toml

# Export to static files
python export.py --output ./docs

# Push to GitHub (Pages serves from /docs)
git add docs/
git commit -m "Update site"
git push
```

### Scenario: Team Documentation

**Best deployment:** Docker for everyone, dynamic server in production

```bash
# Everyone on the team uses Docker
docker-compose up

# Production uses dynamic Python server
# for real-time updates when docs change
```

### Scenario: Photography Portfolio

**Best deployment:** Local development, Docker for staging, static export for production

High-performance static site with CDN for fast image delivery.

## Troubleshooting

### Port Already in Use

```
OSError: [Errno 48] Address already in use
```

**Solution:** Change `listen_port` in config.toml or stop the other service using that port.

### Module Not Found

```
ModuleNotFoundError: No module named 'flask'
```

**Solution:** Install dependencies:
```bash
pip install -r requirements.txt
```

### Permission Denied

```
PermissionError: [Errno 13] Permission denied
```

**Solution:** Check directory permissions:
```bash
chmod -R 755 content/ templates/ styles/
```

### Template Not Found

```
Exception: Base template not found
```

**Solution:** Ensure `base.html` exists in templates directory:
```bash
ls templates/base.html
```

## Next Steps

Choose your deployment path:

- **[Local Development Guide](deployment/local-development.md)** - Start here for development
- **[Docker Deployment Guide](deployment/docker.md)** - Containerized deployment
- **[Production Deployment Guide](deployment/production.md)** - Go live with your site

## Security Considerations

### Development

- **Only bind to localhost** (`listen_address = "127.0.0.1"`)
- **Never commit config.toml** with sensitive data to version control

### Production

- **Use HTTPS** - Always use TLS/SSL in production
- **Strong passwords** - If using admin interface, use strong passwords
- **Firewall rules** - Only expose necessary ports
- **Regular updates** - Keep Foldsite and dependencies updated
- **Content validation** - Be careful with user-uploaded content

See [Production Deployment](production.md) for detailed security guidance.

## Performance Tips

### For All Deployments

- **Use hidden files** for drafts (`___draft.md`) to avoid processing
- **Optimize images** before uploading (Foldsite generates thumbnails, but smaller source = faster)
- **Minimize template complexity** - Simple templates render faster

### For Production

- **Enable caching** at the web server level
- **Use a CDN** for static assets
- **Compress responses** with gzip/brotli
- **Monitor resource usage** and scale as needed

## Getting Help

Need assistance with deployment?

- **[Support](../support.md)** - Community help and resources
- **GitHub Issues** - Report bugs or ask questions
- **Example Configs** - See `/examples` directory in repository

Happy deploying!