blinko Documentation

An open-source, self-hosted personal AI note tool prioritizing privacy, built using TypeScript .

10,343 stars TypeScript TypeScript 1 file · ~3,366 tokens #markdown#memos#nextjs#notebook#openai#postgres#react#self-hosted
RAW Doc

Docker & Self-Hosted Deployment Verified OCI

Deploy blinko on any server, homelab, or cloud container platform.

1-Click Terminal Command
bash (docker run) 
docker run -d --name blinko -p 1111:1111 --restart always blinkospace/blinko:latest
Configured Services & Ports
⚙️ mock-openai
image: node:20-alpine
⚙️ postgres
image: postgres:15-alpine
⚙️ blinko
image: blinkospace/blinko:latest
🔌 Ports: 1111:1111
docker-compose.yml
yaml (docker-compose.yml) 
version: '3.8'

services:
  # Mock OpenAI API for testing Docker internal network connectivity
  mock-openai:
    image: node:20-alpine
    container_name: mock-openai
    working_dir: /app
    command: node server.js
    volumes:
      - ./mock-openai:/app
    networks:
      - blinko-test-network
    healthcheck:
      test: ["CMD", "wget", "-q", "--spider", "http://localhost:8080/models"]
      interval: 10s
      timeout: 5s
      retries: 3

  # PostgreSQL database
  postgres:
    image: postgres:15-alpine
    container_name: blinko-test-postgres
    environment:
      POSTGRES_USER: blinko
      POSTGRES_PASSWORD: blinko
      POSTGRES_DB: blinko
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - blinko-test-network
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U blinko"]
      interval: 10s
      timeout: 5s
      retries: 5

  # Blinko application
  blinko:
    image: blinkospace/blinko:latest
    container_name: blinko-test
    depends_on:
      postgres:
        condition: service_healthy
      mock-openai:
        condition: service_healthy
    environment:
      - DATABASE_URL=postgresql://blinko:blinko@postgres:5432/blinko
      - NEXTAUTH_SECRET=test-secret-key-for-testing
      - NEXTAUTH_URL=http://localhost:1111
    ports:
      - "1111:1111"
    networks:
      - blinko-test-network

networks:
  blinko-test-network:
    driver: bridge

volumes:
  postgres_data:

File: README.md

Blinko

Live Demo: username:blinko password:blinko

Blinko is an AI-powered card note-taking project. Designed for individuals who want to quickly capture and organize their fleeting thoughts. Blinko allows users to seamlessly jot down ideas the moment they strike, ensuring that no spark of creativity is lost.

🚀Main Features

  • 🤖AI-Enhanced Note Retrieval ：With Blinko's advanced AI-powered RAG (Retrieval-Augmented Generation), you can quickly search and access your notes using natural language queries, making it effortless to find exactly what you need.

  • 🔒Data Ownership :Your privacy matters. All your notes and data are stored securely in your self-hosted environment, ensuring complete control over your information.

  • 🚀Efficient and Fast :Capture ideas instantly and store them as plain text for easy access, with full Markdown support for quick formatting and seamless sharing.

  • 💡Lightweight architecture with multi-platform support :Built with Tauri, Blinko features a clean and lightweight architecture that delivers robust performance while maintaining exceptional speed and efficiency, with native support for multi-platform deployment including macOS, Windows, Android, and Linux.

  • 🔓Open for Collaboration :As an open-source project, Blinko invites contributions from the community. All code is transparent and available on GitHub, fostering a spirit of collaboration and constant improvement.

📦Start with Docker in seconds

bash
curl -s https://raw.githubusercontent.com/blinko-space/blinko/main/install.sh | bash

👨🏼‍💻Contribution

Contributions are the heart of what makes the open-source community so dynamic, creative, and full of learning opportunities. Your involvement helps drive innovation and growth. We deeply value any contribution you make, and we're excited to have you as part of our community. Thank you for your support! 🙌

Sponsorship

If you find Blinko valuable, consider supporting us! Your contribution will enable us to continue enhancing and maintaining the project for everyone. Thank you for helping us grow. If you'd like to deploy Blinko, you can also use PikaPods to support Blinko. 20% of the deployment fees generated on PikaPods will be contributed to Blinko.

https://ko-fi.com/blinkospace

https://afdian.com/a/blinkospace/plan

Star History

FAQ

Q: Why does the MacOS device installation show as damaged?

A: macOS adds an attribute called com.apple.quarantine to apps that are not notarized when downloading or installing them. This command is used to manually remove that attribute. Run sudo xattr -rd com.apple.quarantine /Applications/blinko.app

File: app/README.md

Tauri + React + Typescript

This template should help get you started developing with Tauri, React and Typescript in Vite.

File: helm/README.md

Blinko Helm Chart

A Helm chart for deploying Blinko, a note-taking application, on Kubernetes.

Prerequisites

  • Kubernetes 1.19+
  • Helm 3.2.0+

Installing the Chart

To install the chart with the release name my-blinko:

bash
# Add the Bitnami repository (required for PostgreSQL dependency)
helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo update

# Install Blinko with built-in PostgreSQL
helm install my-blinko ./helm

# Or install from a packaged chart
helm package ./helm
helm install my-blinko blinko-0.1.0.tgz

Uninstalling the Chart

To uninstall/delete the my-blinko deployment:

bash
helm delete my-blinko

Configuration

The following table lists the configurable parameters and their default values.

Global Parameters

Parameter Description Default
replicaCount Number of Blinko replicas 1
image.repository Blinko image repository blinko
image.tag Blinko image tag "" (uses appVersion)
image.pullPolicy Image pull policy IfNotPresent
nameOverride Override the name of the chart ""
fullnameOverride Override the full name of the chart ""

Service Parameters

Parameter Description Default
service.type Kubernetes service type ClusterIP
service.port Service port 1111
service.targetPort Target port 1111

Ingress Parameters

Parameter Description Default
ingress.enabled Enable ingress false
ingress.className Ingress class name ""
ingress.annotations Ingress annotations {}
ingress.hosts Ingress hosts configuration [{host: "blinko.local", paths: [{path: "/", pathType: "Prefix"}]}]
ingress.tls Ingress TLS configuration []

Application Configuration

Parameter Description Default
config.baseUrl Base URL for the application "http://localhost:1111"
config.nextauth.url NextAuth URL "http://localhost:1111"
config.nextauth.secret NextAuth secret "my_ultra_secure_nextauth_secret"
config.nodeEnv Node environment "production"

Database Configuration

Built-in PostgreSQL (Default)

Parameter Description Default
postgresql.enabled Enable built-in PostgreSQL true
postgresql.auth.postgresPassword PostgreSQL admin password "mysecretpassword"
postgresql.auth.username PostgreSQL username "postgres"
postgresql.auth.password PostgreSQL password "mysecretpassword"
postgresql.auth.database PostgreSQL database name "postgres"
postgresql.primary.persistence.enabled Enable PostgreSQL persistence true
postgresql.primary.persistence.size PostgreSQL storage size 8Gi

External Database

Parameter Description Default
externalDatabase.enabled Use external database false
externalDatabase.type Database type postgresql
externalDatabase.host Database host ""
externalDatabase.port Database port 5432
externalDatabase.database Database name postgres
externalDatabase.username Database username postgres
externalDatabase.password Database password ""
externalDatabase.existingSecret Existing secret with database credentials ""
externalDatabase.existingSecretPasswordKey Key in existing secret containing password "password"

Resource Management

Parameter Description Default
resources CPU/Memory resource requests/limits {}
autoscaling.enabled Enable HPA false
autoscaling.minReplicas Minimum replicas 1
autoscaling.maxReplicas Maximum replicas 100
autoscaling.targetCPUUtilizationPercentage Target CPU utilization 80

Examples

Installing with External PostgreSQL

bash
helm install my-blinko ./helm \
  --set postgresql.enabled=false \
  --set externalDatabase.enabled=true \
  --set externalDatabase.host=my-postgres-host \
  --set externalDatabase.password=mypassword

Installing with Ingress

bash
helm install my-blinko ./helm \
  --set ingress.enabled=true \
  --set ingress.hosts[0].host=blinko.example.com \
  --set ingress.hosts[0].paths[0].path="/" \
  --set ingress.hosts[0].paths[0].pathType="Prefix"

Installing with Custom Configuration

bash
helm install my-blinko ./helm \
  --set config.baseUrl="https://blinko.example.com" \
  --set config.nextauth.url="https://blinko.example.com" \
  --set config.nextauth.secret="your-super-secret-key" \
  --set resources.requests.memory="256Mi" \
  --set resources.requests.cpu="250m"

Installing with External Database using Existing Secret

bash
# Create a secret with database credentials
kubectl create secret generic my-db-secret --from-literal=password=mydbpassword

# Install Blinko
helm install my-blinko ./helm \
  --set postgresql.enabled=false \
  --set externalDatabase.enabled=true \
  --set externalDatabase.host=my-postgres-host \
  --set externalDatabase.existingSecret=my-db-secret \
  --set externalDatabase.existingSecretPasswordKey=password

Upgrading

To upgrade the chart:

bash
helm upgrade my-blinko ./helm

Backup and Restore

Backup PostgreSQL Data

If using the built-in PostgreSQL:

bash
# Get the PostgreSQL password
export POSTGRES_PASSWORD=$(kubectl get secret my-blinko-postgresql -o jsonpath="{.data.postgres-password}" | base64 -d)

# Create a backup
kubectl exec -it my-blinko-postgresql-0 -- pg_dump -U postgres -d postgres > blinko-backup.sql

Restore PostgreSQL Data

bash
# Restore from backup
kubectl exec -i my-blinko-postgresql-0 -- psql -U postgres -d postgres < blinko-backup.sql

Troubleshooting

Check Pod Status

bash
kubectl get pods -l app.kubernetes.io/name=blinko

View Logs

bash
kubectl logs -l app.kubernetes.io/name=blinko

Check Database Connection

bash
kubectl exec -it deployment/my-blinko -- env | grep DATABASE

Connect to PostgreSQL

bash
export POSTGRES_PASSWORD=$(kubectl get secret my-blinko-postgresql -o jsonpath="{.data.postgres-password}" | base64 -d)
kubectl run my-blinko-postgresql-client --rm --tty -i --restart='Never' --image docker.io/bitnami/postgresql:15 --env="PGPASSWORD=$POSTGRES_PASSWORD" --command -- psql --host my-blinko-postgresql -U postgres -d postgres -p 5432

Dependencies

This chart depends on:

Contributing

Please read the contribution guidelines before submitting pull requests.

File: test-docker/README.md

Docker Internal Network Test for Blinko AI Provider

This directory contains test files to verify that the AI provider model fetching works correctly through Docker internal networks.

Problem Solved

Previously, the fetchProviderModels function made HTTP requests directly from the browser, which meant Docker internal hostnames (like http://ollama:11434) were not accessible.

This fix moves the model fetching logic to the backend server, allowing containers to communicate through Docker's internal network.

Test Setup

1. Start the test environment

bash
cd test-docker
docker-compose -f docker-compose.test.yml up -d

2. Wait for services to be ready

bash
docker-compose -f docker-compose.test.yml ps

All services should show as "healthy".

3. Access Blinko

Open http://localhost:1111 in your browser.

4. Test the fix

  1. Go to Settings > AI Settings
  2. Add a new Provider:
    • Provider Type: OpenAI or Custom
    • Base URL: http://mock-openai:8080/v1
    • API Key: test-key (any value works for the mock)
  3. Click "Fetch Models" button
  4. Expected Result: You should see 3 models listed:
    • gpt-4o
    • gpt-4o-mini
    • gpt-3.5-turbo

5. Verify in logs

bash
docker logs mock-openai

You should see requests like:

text
2024-XX-XX... - GET /v1/models
Returning model list...

This confirms the request came from the Blinko container (server-side), not from the browser.

Cleanup

bash
docker-compose -f docker-compose.test.yml down -v

File: README.zh-CN.md

Blinko

在线演示账号: username:blinko password:blinko

Blinko 是一个AI驱动的卡片笔记项目，专为那些想要快速捕捉和组织灵感的人设计。它允许用户在灵感闪现的瞬间无缝记录想法，确保不错过任何创意火花。

🚀主要特性

  • 🤖AI 增强笔记检索：通过 Blinko 的先进 AI 驱动的 RAG（检索增强生成）技术，你可以使用自然语言查询快速搜索和访问笔记，轻松找到所需内容。支持 OpenAI、Azure OpenAI 和 Ollama。

  • 🔒数据所有权：你的隐私至关重要。所有笔记和数据都安全存储在你的自托管环境中，确保对信息的完全控制。

  • 🚀高效快速：即时捕捉想法并以纯文本形式存储以便于访问，完全支持 Markdown 格式，便于快速排版和分享。

  • 💡轻量架构，多端支持：基于 Tauri 构建的 Blinko 采用简洁轻量的架构，在保持卓越速度和效率的同时，并且支持Macos,Windows,Android,Linux等多平台。

  • 🔓开放协作：作为开源项目，Blinko 欢迎社区贡献。所有代码都在 GitHub 上公开透明，培养协作和持续改进的精神。

🤖 AI 模型支持

OpenAI

  • 支持 OpenAI API
  • 支持自定义 API 地址
  • 支持 Azure OpenAI

Ollama

  • 支持本地部署
  • 默认地址：http://127.0.0.1:11434
  • 支持所有 Ollama 模型
  • 完全免费，无需 API Key

📦快速开始（Docker Compose）

bash
curl -s https://raw.githubusercontent.com/blinko-space/blinko/main/install.sh | bash

👨🏼‍💻贡献

贡献是开源社区充满活力、创造力和学习机会的核心。你的参与有助于推动创新和发展。我们深深感谢任何形式的贡献，并很高兴有你成为我们社区的一部分。感谢你的支持！🙌

赞助

如果你觉得 Blinko 有价值，请考虑支持我们！你的贡献将使我们能够继续为所有人改进和维护这个项目。感谢你帮助我们成长，如果你想部署blinko,你也可以使用 PikaPods 来支持 Blinko,在pikapods上部署产生的费用有20%会贡献给Blinko。

https://ko-fi.com/blinkospace

https://afdian.com/a/blinkospace/plan

Star 历史

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#markdown Browse markdown catalog → #memos Browse memos catalog → #nextjs Browse nextjs catalog → #notebook Browse notebook catalog → #openai Browse openai catalog → #postgres Browse postgres catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →