blinko-cloudron/NOTES.md

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

# 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