that initial commit

2025-11-18 19:21:31 -07:00
commit a68fd570c7
69 changed files with 31070 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,201 @@
+# 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/)