From 42cba7045420ff141b75f2925db33b70775f3322 Mon Sep 17 00:00:00 2001 From: Nathan Date: Mon, 9 Jun 2025 11:06:35 +0800 Subject: [PATCH 1/2] docs: support localhost development --- README.md | 90 ++++++++++++++++----- .development.env => deploy.env | 0 dev.env | 4 + doc/DEPLOYMENT.md | 143 +++++++++++++++++++++++++++++++++ 4 files changed, 215 insertions(+), 22 deletions(-) rename .development.env => deploy.env (100%) create mode 100644 dev.env create mode 100644 doc/DEPLOYMENT.md diff --git a/README.md b/README.md index c155dfdd..0c861e50 100644 --- a/README.md +++ b/README.md @@ -24,6 +24,19 @@ Bring projects, wikis, and teams together with AI ![appflowy_web_quick_note_large](https://github.com/user-attachments/assets/5c633e60-6f34-454c-91db-236a1b78966a) ![appflowy_web_share](https://github.com/user-attachments/assets/64b9955d-b11f-4aa1-b32b-ea79ea7f3566) +## Table of Contents + +- [Use Cases](#use-cases) +- [Features](#features) +- [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) + ## Use cases - Build and maintain a knowledge base for your team - Create and publish documentation for your customers and audience @@ -39,12 +52,6 @@ Bring projects, wikis, and teams together with AI ## AppFlowy Web roadmap >Features listed below are available in AppFlowy desktop and mobile applications (Download). -Q1 2025: -- Templates -- Favorite pages -- Import and export markdown files -- More document features incl. simple table and column layout -- AI Chat and AI Writer ## Installation ### Cloud: we host AppFlowy for you @@ -62,32 +69,71 @@ Join our Discord server to get help! ![Docker](https://img.shields.io/badge/Docker-2496ED?style=for-the-badge&logo=docker&logoColor=white) ## Development -### Pre-requisite -AppFlowy Cloud must be running and accessible by AppFlowy Web. If you alredy have AppFlowy Cloud running, you can skip this step. -For local development, please follow the steps below: +### 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. Copy deploy.env to .env, then run `docker-compose up -d`. -4. The AppFlowy Cloud API should be running on localhost:80, and allow CORS from localhost:3000 by default. -5. Setup at least one sign in method: SMTP for magic link, or using an OAuth provider. Refer to AppFlowy Cloud repository for more details. +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. Copy .development.env to .env. The default value assumes that AppFlowy Cloud is deployed on localhost. If not, please update the value of the API endpoints. -2. Make sure `npm` has been installed on your dev environment, then run the following: -``` -corepack enable -pnpm install +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 + ``` -pnpm run dev -``` - -Open your browser to visit localhost:3000 +3. **Open your browser** and visit http://localhost:3000 ## Deployment Once AppFlowy Cloud has been setup, you can follow the [deployment guide](https://appflowy.com/docs/self-host-appflowy-run-appflowy-web) to deploy AppFlowy Web. +## Documentation + +- **[Deployment Guide](doc/DEPLOYMENT.md)** - Detailed environment configuration, architecture diagrams, and troubleshooting +- **[AppFlowy Cloud Repository](https://github.com/AppFlowy-IO/AppFlowy-Cloud)** - Backend setup and configuration +- **[Official Documentation](https://appflowy.com/docs)** - Complete AppFlowy documentation + ## License Distributed under the AGPLv3 License. See [`LICENSE.md`](https://github.com/AppFlowy-IO/AppFlowy-Web/blob/main/LICENSE) for more information. diff --git a/.development.env b/deploy.env similarity index 100% rename from .development.env rename to deploy.env diff --git a/dev.env b/dev.env new file mode 100644 index 00000000..dcde6f63 --- /dev/null +++ b/dev.env @@ -0,0 +1,4 @@ +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 \ No newline at end of file diff --git a/doc/DEPLOYMENT.md b/doc/DEPLOYMENT.md new file mode 100644 index 00000000..2f71e762 --- /dev/null +++ b/doc/DEPLOYMENT.md @@ -0,0 +1,143 @@ +# 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 From f88b7483985258272f64d282c03ca644e1607b49 Mon Sep 17 00:00:00 2001 From: Nathan Date: Mon, 9 Jun 2025 13:19:49 +0800 Subject: [PATCH 2/2] docs: create development guide --- README.md | 59 +--------------- doc/DEPLOYMENT.md | 143 --------------------------------------- doc/DEVELOPMENT_GUIDE.md | 91 +++++++++++++++++++++++++ 3 files changed, 92 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..076855d3 --- /dev/null +++ b/doc/DEVELOPMENT_GUIDE.md @@ -0,0 +1,91 @@ +## 🎯 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) + +```bash +# Clone AppFlowy Cloud repository +git clone https://github.com/AppFlowy-IO/AppFlowy-Cloud.git +cd AppFlowy-Cloud + +# Use development configuration +cp dev.env .env + +# 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 + +# Use matching development configuration +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 +cp deploy.env .env + +# 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