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