blinko-cloudron/BUILD.md

Blinko Cloudron Package - Build Instructions

Prerequisites

• Cloudron CLI installed (npm install -g cloudron)
• Docker installed
• Access to build service: builder.docker.due.ren
• Build service token configured

Package Structure

blink-cloudron/
├── CloudronManifest.json    # Cloudron app manifest
├── Dockerfile               # Container build definition
├── start.sh                 # Initialization and startup script
├── nginx.conf               # NGINX reverse proxy configuration
├── supervisor/
│   └── supervisord.conf     # Process management configuration
├── logo.png                 # App icon (required)
└── BUILD.md                 # This file

Configuration Details

Application

• App ID: io.blinko.cloudronapp
• Internal Port: 1111 (Blinko Node.js server)
• External Port: 8000 (NGINX proxy)
• Memory Limit: 512MB

Addons

• PostgreSQL: Database storage for notes and user data
• Local Storage: Persistent file storage at /app/data

Environment Variables (Auto-configured)

Variable	Source	Description
DATABASE_URL	CLOUDRON_POSTGRESQL_URL	PostgreSQL connection string
NEXTAUTH_URL	CLOUDRON_APP_ORIGIN	Application URL for authentication
NEXT_PUBLIC_BASE_URL	CLOUDRON_APP_ORIGIN	Public-facing URL
NEXTAUTH_SECRET	Auto-generated	Session encryption key
NODE_ENV	production	Runtime environment
TRUST_PROXY	1	Trust reverse proxy headers

Build Commands

1. Get the logo

Download or create a logo.png file (256x256 recommended):

# Download from Blinko repository
curl -o logo.png https://raw.githubusercontent.com/blinkospace/blinko/main/public/logo.svg
# Convert to PNG if needed (requires ImageMagick)
# convert logo.svg -resize 256x256 logo.png

2. Build the package

cloudron build \
  --set-build-service builder.docker.due.ren \
  --build-service-token e3265de06b1d0e7bb38400539012a8433a74c2c96a17955e \
  --set-repository andreasdueren/blinko-cloudron \
  --tag 1.0.0

3. Install the package

cloudron install \
  --location blinko.due.ren \
  --image andreasdueren/blinko-cloudron:1.0.0

4. View logs during installation

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

Important: Don't wait more than 30 seconds for installation feedback. If there's an error, the install command may hang indefinitely.

Troubleshooting

Check application logs

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

Shell into the container

cloudron exec --app blinko.due.ren

Common issues

1. Database connection fails

   • Check PostgreSQL addon is properly configured
   • Verify DATABASE_URL environment variable

2. Authentication issues

   • Ensure NEXTAUTH_URL matches the app domain
   • Check that NEXTAUTH_SECRET was generated

3. Static files not loading

   • Verify NGINX is running: supervisorctl status
   • Check NGINX logs for errors

4. Memory issues

   • Increase memoryLimit in CloudronManifest.json if needed
   • Monitor with: cloudron status --app blinko.due.ren

Rebuild after changes

Always uninstall and reinstall fresh during development:

cloudron uninstall --app blinko.due.ren
cloudron build --set-build-service builder.docker.due.ren \
  --build-service-token e3265de06b1d0e7bb38400539012a8433a74c2c96a17955e \
  --set-repository andreasdueren/blinko-cloudron \
  --tag 1.0.1
cloudron install --location blinko.due.ren --image andreasdueren/blinko-cloudron:1.0.1

Data Persistence

All persistent data is stored in /app/data:

• /app/data/.blinko - Application data directory
• /app/data/.nextauth_secret - Authentication secret
• /app/data/.initialized - First-run marker

This directory is automatically backed up by Cloudron.

References

• Blinko Documentation
• Blinko GitHub
• Cloudron Packaging Guide
• Cloudron Manifest Reference
• Cloudron Addons