Blinko on Render

Self-host Blinko, an AI-assisted personal note app, on Render with managed Postgres and persistent file storage.

Blinko is an open-source, self-hosted note-taking app for capturing short ideas, searching notes, and adding AI-assisted retrieval on top of your own data. This template deploys the upstream Blinko Docker image on Render, wires it to Render Postgres, and attaches a persistent disk for Blinko's local app data.

This repo is a thin deployment wrapper. The application code and Docker image come from blinkospace/blinko.

• Why deploy Blinko on Render
• Use cases
• What gets deployed
• Quickstart
• Configuration
• Default capacity
• Cost breakdown
• Customization
• Operations
• Upgrading
• Troubleshooting
• FAQ
• Security
• Caveats and limitations
• Credits and license

Why deploy Blinko on Render

• Managed Postgres wired automatically - no manual connection string setup.
• Persistent local app data - files under /app/.blinko survive deploys and restarts.
• Generated auth secret - Render creates NEXTAUTH_SECRET during the first apply.
• Public HTTPS endpoint - Render provides TLS and an onrender.com URL by default.
• Small wrapper repo - the template stays close to upstream Blinko releases.

Use cases

• Personal note capture - keep short notes, links, and ideas in a private workspace.
• Self-hosted AI note search - connect your own model provider from Blinko's settings.
• Markdown knowledge base - store searchable notes without giving data to a hosted note app.
• Internal team scratchpad - deploy one shared Blinko instance for lightweight knowledge capture.
• Experiment with Blinko plugins and API routes - fork the template and keep infrastructure reproducible.

What gets deployed

flowchart LR
  user["Browser"] -->|HTTPS| web["blinko<br/>web service"]
  web -->|Postgres connection string| db[("blinko-db<br/>Render Postgres")]
  web -.writes files.-> disk[/"blinko-data<br/>persistent disk"/]

Loading

Resource	Type	Plan	Purpose
blinko	Web service (Docker wrapper)	standard	Runs blinkospace/blinko:latest on port 1111.
blinko-db	Render Postgres	basic-256mb	Stores Blinko application data.
blinko-data	Persistent disk	2 GB	Persists files written under /app/.blinko.

Region: oregon. Change the region fields in render.yaml before deploying if you need another Render region. Keep the web service and database in the same region.

Default capacity:

• standard web service: chosen as the gallery default because Blinko runs a full Node/Bun app with Prisma, background jobs, file handling, and optional AI integrations.
• numInstances: 1: required because the service has a persistent disk. Scale vertically by changing the plan.
• basic-256mb Postgres: enough for initial personal and small-team installs. Upgrade if database metrics show sustained pressure.
• 2 GB disk: enough for small personal installs. Increase it before storing many uploads.

Quickstart

1. Click Deploy to Render.
2. Authorize the Render GitHub App and choose where Render should fork this template.
3. Review the Blueprint. You do not need to set NEXTAUTH_URL or NEXT_PUBLIC_BASE_URL for the initial deploy.
4. Click Apply. The first deploy usually takes a few minutes while Render pulls the image, creates Postgres, and starts Blinko.
5. Open https://<your-service>.onrender.com/health and confirm it returns {"status":"ok"}.
6. Open the blinko service URL after it is live and create your first account.
7. If you add a custom domain or configure SSO, set NEXTAUTH_URL and NEXT_PUBLIC_BASE_URL to the final public URL and redeploy.

Configuration

Required secrets

None for the initial deploy. Render generates the auth secret, wires Postgres automatically, and injects the public Render hostname at runtime. You only need to provide URL values if you use a custom domain or SSO.

Env var	What it is for	How to get it
NEXTAUTH_URL	Canonical public URL for auth callbacks. Required for custom domains and most SSO setups.	Your custom domain, including https://.
NEXT_PUBLIC_BASE_URL	Public base URL used by the frontend.	Usually the same value as NEXTAUTH_URL.

For the default onrender.com URL, entrypoint.sh builds both values from Render's RENDER_EXTERNAL_HOSTNAME as https://$RENDER_EXTERNAL_HOSTNAME.onrender.com. If the hostname already contains a dot, the script uses it as-is.

Auto-generated secrets

Env var	Purpose
NEXTAUTH_SECRET	Session and auth signing secret generated by Render.

Do not rotate NEXTAUTH_SECRET casually. Existing sessions can be invalidated.

Wired automatically

Env var	Source
DATABASE_URL	blinko-db.connectionString via fromDatabase.

Optional tweaks

Env var	Default	What it does
NODE_ENV	production	Runs Blinko in production mode.
PORT	1111	Matches the port used by the upstream Blinko server.
TRUST_PROXY	1	Tells the app it is behind Render's proxy.
DISABLE_SECURE_COOKIE	false	Keeps cookies secure when served over Render HTTPS.

Blinko's AI provider configuration is normally handled inside the Blinko UI after deploy. See the upstream Blinko docs for provider-specific settings.

Default capacity

The template defaults to a standard web service, basic-256mb Postgres, one web instance, and a 2 GB disk. That is the safest first-run profile for a public gallery template: the app has enough memory to start reliably, migrations have room to run, and users can store local Blinko files without losing them on deploy.

For a personal install with light note volume, you can try changing the web service plan from standard to starter after the first successful deploy. If startup logs show memory pressure, health checks fail before the app binds port 1111, or AI/file workflows feel sluggish, move back to standard.

For a shared or heavier install, scale vertically. Increase the web service plan first, then increase the Postgres plan if database CPU, memory, storage, or connection metrics show sustained pressure. The persistent disk means horizontal scaling is not available for this template.

Cost breakdown

Resource	Plan	Monthly cost
blinko	standard	$25
blinko-db	basic-256mb	$6
blinko-data	2 GB disk	$0.50
Total		$31.50

Prices can change. Check Render pricing before publishing or budgeting a production install.

Cheaper: try changing the web service to starter after a successful deploy if your note volume is small.

Scale up: increase the web service plan first, then scale the Postgres plan if database metrics show pressure.

Customization

Pin the Blinko version

The wrapper defaults to the upstream latest image:

ARG BLINKO_IMAGE=docker.io/blinkospace/blinko:latest

For production, pin a known-good Blinko tag:

ARG BLINKO_IMAGE=docker.io/blinkospace/blinko:1.8.7

Commit the change and redeploy.

Add a custom domain

Add the domain in the Render Dashboard after the first deploy. Then set both NEXTAUTH_URL and NEXT_PUBLIC_BASE_URL to https://your-domain.example and redeploy. This is especially important for SSO providers because callback URLs must match exactly.

Change the region

Edit every region: oregon value in render.yaml before deploying:

region: frankfurt

Keep all resources in the same region so the web service uses the private network path to Postgres.

Resize persistent storage

Increase the disk if you store many uploads:

disk:
  name: blinko-data
  mountPath: /app/.blinko
  sizeGB: 10

Render disks can grow, but they cannot shrink.

Enable PR previews

Templates disable preview environments by default:

previews:
  generation: off

Change this to manual or automatic in your fork if you want preview stacks for template changes.

Migrate an existing Blinko install

This template separates Blinko state into two places:

• Render Postgres stores structured app data.
• The blinko-data disk stores files under /app/.blinko.

To migrate an existing install, export your current Postgres database with pg_dump, restore it into blinko-db, then copy the contents of your existing Blinko data directory into /app/.blinko on the web service. Keep the upstream Blinko version aligned while you migrate. Upgrade only after the restored instance starts cleanly.

Operations

Backups

Render Postgres includes backups according to the selected database plan. The persistent disk also has automatic snapshots. Export data before deleting either resource because deleted databases and disks are not recoverable from this template.

For extra safety before a major Blinko upgrade, take a manual Postgres export and copy important files out of /app/.blinko.

Monitoring

Use the Render Dashboard metrics for CPU, memory, disk, and Postgres health. The web service health check uses /health, which returns JSON when the Express server is running.

Scaling

The web service uses a persistent disk, so it is single-instance. Vertical scaling is available by changing the service plan. Horizontal scaling is not available while the disk is attached.

Watch memory first. If memory stays high during normal usage, move from standard to pro. If database metrics show sustained pressure, upgrade blinko-db.

Logs

Open the blinko service in the Render Dashboard and view Logs for startup, migrations, and runtime errors. The upstream image runs Prisma migrations before starting the server.

Upgrading

Pick Up Upstream Releases

If you keep BLINKO_IMAGE set to latest, trigger a manual deploy when you want Render to pull the current image. For a pinned tag, edit Dockerfile, commit the new tag, and redeploy.

Breaking-Change Migrations

Check upstream Blinko release notes before upgrading across major versions. The image runs Prisma migrations on startup, so database schema changes apply during deploy.

Troubleshooting

Deploy Fails During Image Pull

Cause: Docker Hub is unavailable, the image tag does not exist, or a pinned tag was mistyped.

Fix: Verify the tag on Docker Hub, then update BLINKO_IMAGE in Dockerfile or retry the deploy.

Health check fails

Cause: Blinko did not start on port 1111, migrations failed, or the instance ran out of memory before binding the port.

Fix: Check the blinko service logs. If you see memory errors, keep the standard plan or scale up. If you see database errors, confirm DATABASE_URL is wired from blinko-db.

Login or SSO redirects to the wrong URL

Cause: NEXTAUTH_URL or NEXT_PUBLIC_BASE_URL does not match the public URL users visit.

Fix: Set both env vars to the final https://... URL in the Render Dashboard and redeploy. If you configured an OAuth provider, update the provider callback URL too.

First deploy fails during migrations

Cause: Blinko runs Prisma migrations during container startup. A bad database URL, a partially restored database, or a version mismatch can stop startup before the health check passes.

Fix: Check the first error above the migration failure in the blinko logs. For a fresh deploy, confirm DATABASE_URL comes from blinko-db. For a migration, restore a clean database backup and use the same Blinko image tag as the source install.

Uploaded files disappear after deploy

Cause: Files were written outside /app/.blinko, or the disk was removed.

Fix: Keep Blinko file data under /app/.blinko and do not remove the blinko-data disk unless you have exported the files.

AI features do not respond

Cause: Blinko needs model provider settings in the app UI, and external providers need valid API keys or reachable endpoints.

Fix: Configure the provider in Blinko after login. For local model providers, make sure the endpoint is reachable from Render. A model server running on your laptop is not reachable from the Render service unless you expose it securely.

For more detail, check Render deploy logs, the service events timeline, this template repo's issues, and upstream Blinko issues.

FAQ

Can I run this on Render's free plan?

Not as written. The template uses a persistent disk and a paid Postgres plan. You can experiment with cheaper plans, but the default is chosen for a stable first deploy.

Why is there a Dockerfile if Blinko already publishes an image?

The wrapper lets the template set NEXTAUTH_URL and NEXT_PUBLIC_BASE_URL from Render's runtime host. It also gives you one place to pin the upstream image tag.

Where is my note data stored?

Structured app data is in Render Postgres. Files written under /app/.blinko are on the blinko-data persistent disk.

Can I use a custom domain?

Yes. Add the domain in Render, then set NEXTAUTH_URL and NEXT_PUBLIC_BASE_URL to the custom domain URL and redeploy.

Can I migrate an existing Blinko install?

Yes, but this template does not automate migration. Export your existing Postgres data and files, then restore them into blinko-db and /app/.blinko.

Does this include an AI model?

No. The template deploys Blinko. Configure AI providers from the Blinko UI or point Blinko at a reachable provider endpoint after deploy.

Should I pin the Docker image?

Yes for production. latest is convenient for trying the template, but a pinned tag makes upgrades deliberate and easier to roll back.

Can I remove the persistent disk?

Only if you are sure you do not need files stored under /app/.blinko. Removing the disk also changes deploy behavior, but you lose that persistent filesystem state unless you export it first.

Security

• Render terminates TLS for the public web service.
• Postgres traffic stays on Render's private network.
• Render generates NEXTAUTH_SECRET instead of committing a default secret.
• The web service is public. The database is not publicly exposed by this template.
• Rotate SSO provider secrets in the provider dashboard and in Render at the same time.
• Report Blinko security issues to upstream via the process in blinkospace/blinko.

Caveats and limitations

• The web service is single-instance because it has a persistent disk.
• Zero-downtime deploys are not available while the disk is attached.
• latest is convenient but not deterministic. Pin a version for production.
• Custom domains and SSO need explicit NEXTAUTH_URL and NEXT_PUBLIC_BASE_URL values.
• This template does not include an Ollama or other model server.
• This README intentionally does not include a hero screenshot.

Credits and license

• Blinko is maintained at blinkospace/blinko and licensed under GPL-3.0.
• This Render template wrapper is licensed under MIT. See LICENSE.
• Star the upstream project if Blinko is useful to you.