202 lines
5.2 KiB
Markdown
202 lines
5.2 KiB
Markdown
# StarPunk
|
|
|
|
A minimal, self-hosted IndieWeb CMS for publishing notes with RSS syndication.
|
|
|
|
**Current Version**: 0.1.0 (development)
|
|
|
|
## Versioning
|
|
|
|
StarPunk follows [Semantic Versioning 2.0.0](https://semver.org/):
|
|
- Version format: `MAJOR.MINOR.PATCH`
|
|
- Current: `0.1.0` (pre-release development)
|
|
- First stable release will be `1.0.0`
|
|
|
|
**Version Information**:
|
|
- Check version: `python -c "from starpunk import __version__; print(__version__)"`
|
|
- See changes: [CHANGELOG.md](CHANGELOG.md)
|
|
- Versioning strategy: [docs/standards/versioning-strategy.md](docs/standards/versioning-strategy.md)
|
|
|
|
## Philosophy
|
|
|
|
"Every line of code must justify its existence. When in doubt, leave it out."
|
|
|
|
StarPunk is designed for a single user who wants to:
|
|
- Publish short notes to their personal website
|
|
- Own their content (notes stored as portable markdown files)
|
|
- Syndicate via RSS
|
|
- Support IndieWeb standards (Micropub, IndieAuth)
|
|
- Run on minimal resources
|
|
|
|
## Features
|
|
|
|
- **File-based storage**: Notes are markdown files, owned by you
|
|
- **IndieAuth authentication**: Use your own website as identity
|
|
- **Micropub support**: Publish from any Micropub client
|
|
- **RSS feed**: Automatic syndication
|
|
- **No database lock-in**: SQLite for metadata, files for content
|
|
- **Self-hostable**: Run on your own server
|
|
- **Minimal dependencies**: 6 core dependencies, no build tools
|
|
|
|
## Requirements
|
|
|
|
- Python 3.11 or higher
|
|
- 500MB disk space
|
|
- Linux, macOS, or Windows with WSL2
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# Clone repository
|
|
git clone https://github.com/YOUR_USERNAME/starpunk.git
|
|
cd starpunk
|
|
|
|
# Install uv (package manager)
|
|
curl -LsSf https://astral.sh/uv/install.sh | sh
|
|
|
|
# Create virtual environment
|
|
uv venv .venv --python 3.11
|
|
|
|
# Install dependencies
|
|
uv pip install -r requirements.txt
|
|
|
|
# Configure
|
|
cp .env.example .env
|
|
# Edit .env and set ADMIN_ME and SESSION_SECRET
|
|
|
|
# Initialize database
|
|
mkdir -p data/notes
|
|
.venv/bin/python -c "from starpunk.database import init_db; init_db()"
|
|
|
|
# Run development server
|
|
.venv/bin/flask --app app.py run --debug
|
|
|
|
# Visit http://localhost:5000
|
|
```
|
|
|
|
## Configuration
|
|
|
|
All configuration is in the `.env` file. Required settings:
|
|
|
|
- `ADMIN_ME` - Your IndieWeb identity URL (e.g., https://yoursite.com)
|
|
- `SESSION_SECRET` - Random secret key (generate with `python3 -c "import secrets; print(secrets.token_hex(32))"`)
|
|
- `SITE_URL` - Public URL of your site
|
|
|
|
See `.env.example` for all options.
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
starpunk/
|
|
├── app.py # Application entry point
|
|
├── starpunk/ # Application code
|
|
├── data/ # Your notes and database (gitignored)
|
|
│ ├── notes/ # Markdown files
|
|
│ └── starpunk.db # SQLite database
|
|
├── static/ # CSS and JavaScript
|
|
├── templates/ # HTML templates
|
|
└── tests/ # Test suite
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Publishing Notes
|
|
|
|
**Via Web Interface**:
|
|
1. Navigate to `/admin`
|
|
2. Login with your IndieWeb identity
|
|
3. Create notes in markdown
|
|
|
|
**Via Micropub Client**:
|
|
1. Configure client with your site URL
|
|
2. Authenticate via IndieAuth
|
|
3. Publish from any Micropub-compatible app
|
|
|
|
### Backing Up Your Data
|
|
|
|
Your notes are stored as plain markdown files in `data/notes/`. Back up this directory:
|
|
|
|
```bash
|
|
# Simple backup
|
|
tar -czf backup.tar.gz data/
|
|
|
|
# Or use rsync
|
|
rsync -av data/ /backup/starpunk/
|
|
```
|
|
|
|
## Development
|
|
|
|
See [docs/standards/development-setup.md](docs/standards/development-setup.md) for detailed setup.
|
|
|
|
```bash
|
|
# Install dev dependencies
|
|
uv pip install -r requirements-dev.txt
|
|
|
|
# Run tests
|
|
.venv/bin/pytest
|
|
|
|
# Format code
|
|
.venv/bin/black starpunk/ tests/
|
|
|
|
# Lint
|
|
.venv/bin/flake8 starpunk/ tests/
|
|
```
|
|
|
|
## Architecture
|
|
|
|
StarPunk uses a hybrid storage approach:
|
|
- **Notes content**: Markdown files (portable, human-readable)
|
|
- **Metadata**: SQLite database (fast queries)
|
|
|
|
This gives you both portability AND performance.
|
|
|
|
See [docs/architecture/](docs/architecture/) for complete documentation.
|
|
|
|
## IndieWeb Compliance
|
|
|
|
StarPunk implements:
|
|
- [Micropub](https://micropub.spec.indieweb.org/) - Publishing API
|
|
- [IndieAuth](https://indieauth.spec.indieweb.org/) - Authentication
|
|
- [Microformats2](http://microformats.org/) - Semantic HTML markup
|
|
- [RSS 2.0](https://www.rssboard.org/rss-specification) - Feed syndication
|
|
|
|
## Deployment
|
|
|
|
### Production Setup
|
|
|
|
```bash
|
|
# Install gunicorn
|
|
uv pip install gunicorn
|
|
|
|
# Run with gunicorn
|
|
.venv/bin/gunicorn -w 4 -b 127.0.0.1:8000 app:app
|
|
|
|
# Configure nginx/Caddy for HTTPS
|
|
# Set up systemd for process management
|
|
# Enable regular backups of data/ directory
|
|
```
|
|
|
|
See [docs/architecture/deployment.md](docs/architecture/deployment.md) for details.
|
|
|
|
## License
|
|
|
|
MIT License - see LICENSE file
|
|
|
|
## Credits
|
|
|
|
Built with:
|
|
- [Flask](https://flask.palletsprojects.com/) - Web framework
|
|
- [python-markdown](https://python-markdown.github.io/) - Markdown processing
|
|
- [feedgen](https://feedgen.kiesow.be/) - RSS generation
|
|
- [httpx](https://www.python-httpx.org/) - HTTP client
|
|
- [IndieLogin](https://indielogin.com/) - Authentication service
|
|
|
|
## Contributing
|
|
|
|
This is a personal project optimized for single-user use. If you want additional features, consider forking!
|
|
|
|
## Support
|
|
|
|
- Documentation: [docs/](docs/)
|
|
- Issues: GitHub Issues
|
|
- IndieWeb: [indieweb.org](https://indieweb.org/)
|