✨ A free and open source decentralized electronic business card software ✨

📚 Detailed Deployment Guide | 📚 中文部署指南 | 简体中文

• Overview
• Features
• Quick Start
• Environment Configuration
• Local Development
• Build & Deploy
• Project Structure
• Technology Stack
• Contributing
• License

OpenBioCard is a decentralized electronic business card platform built on Cloudflare Workers. It allows users to create and share personalized professional profiles with customizable links and information.

📖 API 文档 | 📖 API Documentation (EN)

• 🌐 Serverless Architecture - Powered by Cloudflare Workers
• 💾 Data Persistence - Using Durable Objects
• 🎨 Modern UI - Vue 3 + Tailwind CSS 4
• 🔒 Secure Authentication - Complete user authentication system
• 🌍 Internationalization - Multi-language interface support
• 📱 Responsive Design - Adapts to all devices
• ⚡ Global Edge Network - Fast content delivery worldwide
• 📦 Monorepo Structure - Managed efficiently with PNPM

• Node.js: v20.x or later
• pnpm: v9.x or later
• Cloudflare Account: Free tier is sufficient

1. Clone the repository

   git clone https://github.com/OpenBioCard/OpenBioCard.git
   cd OpenBioCard

2. Install dependencies

   pnpm install

3. Configure environment variables See Environment Configuration section.

4. Start development server

   pnpm dev

   The application will run on http://localhost:8787.

Create a .dev.vars file in the project root:

# Required secrets
ROOT_USERNAME=root
ROOT_PASSWORD=your_secure_password_here

# Optional environment variables
CORS_ALLOWED_ORIGINS=*
CORS_ALLOWED_METHODS=GET,POST,PUT,DELETE,OPTIONS
CORS_ALLOWED_HEADERS=Content-Type,Authorization

wrangler.jsonc is located in the project root. It handles the Cloudflare Workers configuration, including Durable Objects bindings and migrations.

Use Wrangler CLI to set sensitive information:

# Set root username
pnpm wrangler secret put ROOT_USERNAME

# Set root password
pnpm wrangler secret put ROOT_PASSWORD

# Login to Wrangler
pnpm wrangler login

pnpm dev

This command will start the Vite development server for the frontend, which integrates with the Cloudflare Workers environment via @cloudflare/vite-plugin. It provides a seamless full-stack development experience.

Local Durable Objects data is stored in:

apps/backend/.wrangler/state/v3/do/
├── openbiocard-AdminDO/
└── openbiocard-UserDO/

Generate TypeScript types based on Worker configuration:

pnpm --filter openbiocard-backend cf-typegen

pnpm build

This will build both the frontend and backend applications. The artifacts will be located in:

• Frontend: apps/frontend/dist/
• Backend: apps/backend/dist/ (includes frontend assets)

1. Ensure you're logged in

   pnpm wrangler login

2. Deploy

   pnpm deploy

   This command deploys the backend worker (which serves the frontend assets) to Cloudflare.

3. First-time Durable Objects Setup

   Cloudflare will automatically:

   • Create Durable Objects namespaces
   • Run migrations defined in wrangler.jsonc
   • Bind Durable Objects to your Worker

After deployment, your application will be available at:

https://openbiocard.<your-subdomain>.workers.dev

After deployment, access the following endpoint to initialize the admin user:

https://your-domain.workers.dev/init-admin

OpenBioCard/
├── apps/
│   ├── backend/               # Cloudflare Worker Backend
│   │   ├── durable-objects/   # Durable Objects classes
│   │   ├── router/            # Hono API routes
│   │   ├── middleware/        # Middleware
│   │   ├── types/             # Backend types
│   │   ├── utils/             # Utility functions
│   │   └── index.tsx          # Worker entry point
│   └── frontend/              # Vue 3 Frontend
│       ├── src/               # Source code (if applicable)
│       ├── components/        # Vue components
│       ├── pages/             # Pages (File-based routing)
│       ├── composables/       # Composition API hooks
│       ├── api/               # API clients
│       └── i18n/              # Internationalization
├── docs/                      # Documentation
├── wrangler.jsonc             # Wrangler configuration
├── package.json               # Root package.json (Workspaces)
├── pnpm-workspace.yaml        # PNPM workspace config
└── .dev.vars                  # Local secrets (not committed)

• Vue 3 - Progressive JavaScript framework
• Vue Router - Official routing manager
• Tailwind CSS 4 - Utility-first CSS framework
• Vue I18n - Internationalization plugin
• Vite 6 - Next-generation frontend toolchain

• Cloudflare Workers - Serverless execution environment
• Hono - Lightweight web framework
• Durable Objects - Strongly consistent stateful objects
• TypeScript - Type-safe JavaScript

• PNPM - Fast, disk space efficient package manager
• Wrangler - Cloudflare Workers CLI

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork this project
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Create a Pull Request

This project is licensed under the MIT License - see the LICENSE file for details.

If you encounter any issues or have questions, please open an issue on GitHub.

Made with ❤️ by the OpenBioCard team