From 9ff335283bf84f8868309d471a854a57957157f5 Mon Sep 17 00:00:00 2001 From: Nathan Date: Mon, 9 Jun 2025 13:19:49 +0800 Subject: [PATCH] docs: create development guide --- README.md | 59 +--------------- doc/DEPLOYMENT.md | 143 --------------------------------------- doc/DEVELOPMENT_GUIDE.md | 94 +++++++++++++++++++++++++ 3 files changed, 95 insertions(+), 201 deletions(-) delete mode 100644 doc/DEPLOYMENT.md create mode 100644 doc/DEVELOPMENT_GUIDE.md diff --git a/README.md b/README.md index 0c861e50..2f95f90e 100644 --- a/README.md +++ b/README.md @@ -31,8 +31,6 @@ Bring projects, wikis, and teams together with AI - [AppFlowy Web Roadmap](#appflowy-web-roadmap) - [Installation](#installation) - [Development](#development) - - [Environment Configuration](#environment-configuration) - - [Running AppFlowy Web Locally](#running-appflowy-web-locally) - [Deployment](#deployment) - [Documentation](#documentation) - [License](#license) @@ -49,9 +47,6 @@ Bring projects, wikis, and teams together with AI - Invite members to your workspace for seamless collaboration - Create multiple public and private spaces to better organize your content -## AppFlowy Web roadmap ->Features listed below are available in AppFlowy desktop and mobile applications (Download). - ## Installation ### Cloud: we host AppFlowy for you @@ -70,59 +65,7 @@ Join our Discord server to get help! ## Development -### Prerequisites - -**AppFlowy Cloud Setup:** -AppFlowy Cloud must be running and accessible by AppFlowy Web. If you already have AppFlowy Cloud running, you can skip to the [Environment Configuration](#environment-configuration) section. - -**System Requirements:** -- Node.js ≥18.0.0 -- pnpm ≥10.9.0 -- Docker and Docker Compose (for AppFlowy Cloud) - -**For new AppFlowy Cloud setup:** -1. Install [Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/install/) -2. Clone the AppFlowy Cloud repository -3. **Choose the same configuration pattern for both repositories:** - - **Standard deployment:** `cp deploy.env .env` (both AppFlowy Cloud and AppFlowy Web) - - **Development setup:** `cp dev.env .env` (both AppFlowy Cloud and AppFlowy Web) -4. **Run the appropriate Docker Compose command in AppFlowy Cloud repository:** - - **For deploy.env:** `docker compose up -d` - - **For dev.env:** `docker compose --file ./docker-compose-dev.yml up -d` -5. Set up at least one sign-in method: SMTP for magic link, or using an OAuth provider - -> **📖 For detailed AppFlowy Cloud setup instructions, refer to the [AppFlowy Cloud repository](https://github.com/AppFlowy-IO/AppFlowy-Cloud).** - -### Environment Configuration - -Both AppFlowy Cloud and AppFlowy Web have corresponding environment configurations that must be aligned: - -#### Option 1: Production/Nginx Setup (`deploy.env`) -```bash -cp deploy.env .env -``` -- Use when AppFlowy Cloud is deployed **with nginx** as reverse proxy -- All services accessed through nginx on port 80 - -#### Option 2: Development/Direct Access (`dev.env`) -```bash -cp dev.env .env -``` -- Use when running AppFlowy Cloud services **without nginx** on custom ports -- Direct connections to each service - -> **📖 For detailed configuration information, architecture diagrams, and troubleshooting, see [Deployment Guide](doc/DEPLOYMENT.md)** - -### Running AppFlowy Web Locally -1. **Choose and copy your environment configuration** (see options above) -2. **Install dependencies and start the development server:** - ```bash - corepack enable - pnpm install - pnpm run dev - ``` - -3. **Open your browser** and visit http://localhost:3000 +Check out the [development guide](./doc/DEVELOPMENT_GUIDE.md) for more details ## Deployment Once AppFlowy Cloud has been setup, you can follow the [deployment guide](https://appflowy.com/docs/self-host-appflowy-run-appflowy-web) diff --git a/doc/DEPLOYMENT.md b/doc/DEPLOYMENT.md deleted file mode 100644 index 2f71e762..00000000 --- a/doc/DEPLOYMENT.md +++ /dev/null @@ -1,143 +0,0 @@ -# AppFlowy Web Deployment Guide - -This guide provides information about deploying and configuring AppFlowy Web with AppFlowy-Cloud-Premium backend services. - -## Table of Contents - -- [Environment Configuration Reference](#environment-configuration-reference) - - [`deploy.env` - Production Deployment](#deployenv---production-deployment) - - [`dev.env` - Development Environment](#devenv---development-environment) -- [Configuration Alignment](#configuration-alignment) -- [Creating Custom Configurations](#creating-custom-configurations) - -## Environment Configuration Reference - -### `deploy.env` - Production Deployment - -**AppFlowy-Web Configuration:** -```bash -AF_BASE_URL=http://localhost -AF_GOTRUE_URL=http://localhost/gotrue -AF_WS_URL=ws://localhost/ws/v1 -``` - -**When to use:** -- ✅ Production deployments with Docker Compose -- ✅ Using nginx reverse proxy (default setup) -- ✅ All services accessed through localhost (port 80) - -**How it works:** -- All requests go through nginx reverse proxy -- Backend services run in Docker containers -- Single entry point at `http://localhost` - ---- - -### `dev.env` - Development Environment - -**AppFlowy-Web Configuration:** -```bash -AF_BASE_URL=http://localhost:8000 -AF_GOTRUE_URL=http://localhost:9999 -AF_WS_URL=ws://localhost:8000/ws/v1 -AF_WS_V2_URL=ws://localhost:8000/ws/v2 -``` - -**When to use:** -- ✅ Local development setup -- ✅ Direct connection to services (no nginx) -- ✅ Each service on its own port - -**How it works:** -- Direct connections to individual services -- AppFlowy Cloud API on port 8000 -- GoTrue authentication on port 9999 -- WebSocket connections directly to port 8000 - ---- - -## Configuration Alignment - -The configuration files must match between AppFlowy-Cloud-Premium and AppFlowy-Web: - -**Production Setup:** -```bash -# AppFlowy-Cloud-Premium -cd appflowy-cloud-premium/ -cp deploy.env .env -docker compose up -d - -# AppFlowy-Web -cd ../appflowy-web/ -cp deploy.env .env -pnpm run dev -``` - -**Development Setup:** -```bash -# AppFlowy-Cloud-Premium -cd appflowy-cloud-premium/ -cp dev.env .env -docker compose --file ./docker-compose-dev.yml up -d - -# AppFlowy-Web -cd ../appflowy-web/ -cp dev.env .env -pnpm run dev -``` - -> **⚠️ Important:** Always use matching configuration files (both `deploy.env` or both `dev.env`). - ---- - -## Creating Custom Configurations - -### Remote Production Deployment -```bash -AF_BASE_URL=https://your-domain.com -AF_GOTRUE_URL=https://your-domain.com/gotrue -AF_WS_URL=wss://your-domain.com/ws/v1 -``` - -### Custom Development Ports -```bash -AF_BASE_URL=http://localhost:8001 -AF_GOTRUE_URL=http://localhost:9998 -AF_WS_URL=ws://localhost:8001/ws/v1 -AF_WS_V2_URL=ws://localhost:8001/ws/v2 -``` - ---- - -## Available Environment Variables - -- `AF_BASE_URL` - AppFlowy Cloud API base URL -- `AF_GOTRUE_URL` - Authentication service URL -- `AF_WS_URL` - WebSocket connection URL (v1) -- `AF_WS_V2_URL` - WebSocket connection URL (v2, future use) - ---- - -## Troubleshooting - -**Connection Issues:** -- Verify backend services are running on expected ports -- Check that environment files match between backend and frontend -- Ensure WebSocket URLs use correct protocol (`ws://` or `wss://`) - -**Configuration Validation:** -```bash -# Check your current configuration -cat .env - -# Verify backend is running -docker compose ps -``` - ---- - -## Next Steps - -- [AppFlowy-Cloud-Premium Repository](https://github.com/AppFlowy-IO/AppFlowy-Cloud-Premium) - Backend setup -- [AppFlowy Web README](../README.md) - Frontend quick start guide -- [AppFlowy Documentation](https://appflowy.com/docs) - Official documentation \ No newline at end of file diff --git a/doc/DEVELOPMENT_GUIDE.md b/doc/DEVELOPMENT_GUIDE.md new file mode 100644 index 00000000..c079385b --- /dev/null +++ b/doc/DEVELOPMENT_GUIDE.md @@ -0,0 +1,94 @@ +## 🎯 Overview + +AppFlowy Web requires AppFlowy Cloud as its backend. You can set up this pair in two ways: + +- **🛠️ Development Mode** (`dev.env`) - For local development and testing +- **🚀 Production Mode** (`deploy.env`) - For production deployments with Docker + +## 📋 Prerequisites + +Before you begin, ensure you have: + +- **Node.js** ≥18.0.0 +- **pnpm** ≥10.9.0 +- **Docker & Docker Compose** (required for both modes) + +## 🛠️ Development Mode Setup + +**Best for:** Local development, testing, and debugging individual services. + +### Step-by-Step Setup + +#### 1. Set Up AppFlowy Cloud (Development) + + +> 💡 **Tip**: The `generate_env.sh` script creates a proper `.env` file with all necessary configurations. Check the [AppFlowy Cloud README](https://github.com/AppFlowy-IO/AppFlowy-Cloud/blob/main/README.md) for more details. + +```bash +# Clone AppFlowy Cloud repository +git clone https://github.com/AppFlowy-IO/AppFlowy-Cloud.git +cd AppFlowy-Cloud + +# Use development configuration +# The `generate_env.sh` script creates a proper `.env` file with all necessary configurations. +./script/generate_env.sh + +# Start development server +./script/run_local_server.sh +``` + +#### 2. Set Up AppFlowy Web (Development) + +```bash +# In a new terminal, navigate to your AppFlowy Web directory +cd /path/to/appflowy-web +cp dev.env .env + +# Install dependencies and start +corepack enable +pnpm install +pnpm run dev +``` + + +## 🚀 Production Mode Setup + +**Best for:** Production deployments, staging environments, and containerized setups. + + +#### 1. Set Up AppFlowy Cloud (Production) + +```bash +# Clone AppFlowy Cloud repository +git clone https://github.com/AppFlowy-IO/AppFlowy-Cloud.git +cd AppFlowy-Cloud + +# Use production configuration +# The `generate_env.sh` script creates a proper `.env` file with all necessary configurations. +./script/generate_env.sh + +# Start with Docker Compose +docker compose up -d +``` + +#### 2. Set Up AppFlowy Web (Production) + +```bash +# In a new terminal, navigate to your AppFlowy Web directory +cd /path/to/appflowy-web + +# Use matching production configuration +cp deploy.env .env + +# Install dependencies and start +corepack enable +pnpm install +pnpm run dev +``` + +## 🔗 Additional Resources + +- **[AppFlowy Cloud Repository](https://github.com/AppFlowy-IO/AppFlowy-Cloud)** - Backend setup and configuration +- **[AppFlowy Web README](../README.md)** - Frontend development guide +- **[AppFlowy Documentation](https://appflowy.com/docs)** - Official product documentation +- **[AppFlowy GitHub Discussions](https://github.com/AppFlowy-IO/AppFlowy/discussions)** - Community support