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

```bash
# 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

```bash
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

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

### 4. View logs during installation

```bash
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

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

### Shell into the container

```bash
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:

```bash
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](https://blinko.mintlify.app/)
- [Blinko GitHub](https://github.com/blinkospace/blinko)
- [Cloudron Packaging Guide](https://docs.cloudron.io/packaging/tutorial/)
- [Cloudron Manifest Reference](https://docs.cloudron.io/packaging/manifest/)
- [Cloudron Addons](https://docs.cloudron.io/packaging/addons/)