docs refactor
All checks were successful
All checks were successful
This commit is contained in:
380
docs/content/deployment/index.md
Normal file
380
docs/content/deployment/index.md
Normal file
@ -0,0 +1,380 @@
|
||||
---
|
||||
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!
|
Reference in New Issue
Block a user