# Blinko Cloudron Package - Development Notes

## Application Summary

**Blinko** is an AI-powered card note-taking application with:
- RAG (Retrieval-Augmented Generation) for natural language search
- Markdown support
- Self-hosted, privacy-focused design
- PostgreSQL database backend

## Tech Stack

- **Frontend**: React, Next.js
- **Backend**: Node.js, Express
- **Database**: PostgreSQL 14+
- **ORM**: Prisma
- **Build Tool**: Bun
- **Runtime Port**: 1111

## Key Environment Variables

| Variable | Purpose |
|----------|---------|
| `DATABASE_URL` | PostgreSQL connection string |
| `NEXTAUTH_URL` | App URL for NextAuth.js |
| `NEXT_PUBLIC_BASE_URL` | Public-facing URL |
| `NEXTAUTH_SECRET` | Session encryption secret |
| `TRUST_PROXY` | Enable when behind reverse proxy |
| `TZ` | Timezone setting |

## Cloudron Integration

### Addons Used
- `postgresql` - Database storage
- `localstorage` - Persistent file storage

### Port Mapping
- NGINX listens on port 8000 (Cloudron httpPort)
- Proxies to Blinko on port 1111

### Data Directories
- `/app/data/.blinko` - Application files
- `/app/data/.nextauth_secret` - Auth secret (generated on first run)
- `/app/data/.initialized` - First-run marker

## Build Commands Quick Reference

```bash
# Build
cloudron build \
  --set-build-service builder.docker.due.ren \
  --build-service-token e3265de06b1d0e7bb38400539012a8433a74c2c96a17955e \
  --set-repository andreasdueren/blinko-cloudron \
  --tag VERSION

# Install
cloudron install \
  --location blinko.due.ren \
  --image andreasdueren/blinko-cloudron:VERSION

# Uninstall (for fresh install during development)
cloudron uninstall --app blinko.due.ren

# Logs
cloudron logs --app blinko.due.ren -f

# Shell access
cloudron exec --app blinko.due.ren
```

## Files in Package

| File | Purpose |
|------|---------|
| `CloudronManifest.json` | App metadata, addons, ports |
| `Dockerfile` | Build instructions |
| `start.sh` | Initialization and startup |
| `nginx.conf` | Reverse proxy config |
| `supervisor/supervisord.conf` | Process management |
| `logo.png` | App icon (needs to be added) |

## Known Considerations

1. **First user becomes admin** - The first account registered gets admin privileges
2. **Memory usage** - Set to 512MB, may need adjustment for heavy use
3. **AI features** - Require additional configuration (OpenAI API key, etc.)
4. **File uploads** - 50MB limit configured in NGINX

## Development Rules

- **No AI mentions in commits** - Never mention Claude or AI assistants in git commit messages

## Upstream Resources

- GitHub: https://github.com/blinkospace/blinko
- Docs: https://blinko.mintlify.app/
- Docker: https://hub.docker.com/r/blinkospace/blinko