foldsite/docs/content/deployment/index.md

version, date, author, title, description, summary, quick_tips

version	date	author	title	description	summary	quick_tips
1.0	2025-01-15	DWS Foldsite Team	Deployment Overview	Getting Foldsite running - from local development to production	Learn how to deploy Foldsite in various environments: local development, Docker containers, or production servers.	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

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).

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

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

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

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

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:

gunicorn -w 4 -b 0.0.0.0:8081 main:app

Static Export:

# 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)

   git --version
   

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

For Local Development

1. Python 3.10+

   python3 --version
   

2. pip (Python package manager)

   pip --version
   

For Docker Deployment

1. Docker and Docker Compose

   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:

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

[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

[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

[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:

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

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

# 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

# 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

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

pip install -r requirements.txt

Permission Denied

PermissionError: [Errno 13] Permission denied

Solution: Check directory permissions:

chmod -R 755 content/ templates/ styles/

Template Not Found

Exception: Base template not found

Solution: Ensure base.html exists in templates directory:

ls templates/base.html

Next Steps

Choose your deployment path:

• Local Development Guide - Start here for development
• Docker Deployment Guide - Containerized deployment
• Production Deployment Guide - 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 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 - Community help and resources
• GitHub Issues - Report bugs or ask questions
• Example Configs - See /examples directory in repository

Happy deploying!