381 lines
8.7 KiB
Markdown
381 lines
8.7 KiB
Markdown
---
|
|
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!
|