|
| 1 | +# Chats Development Guide |
| 2 | + |
| 3 | +Welcome to Chats! This guide will help you quickly get started with development and understand how to use and configure the Chats project during the development phase. In the development phase, Chats adopts a front-end and back-end separation model, but in production, they will be combined into a single deployment package. |
| 4 | + |
| 5 | +## Technology Stack |
| 6 | + |
| 7 | +- **Backend:** Developed using C#/ASP.NET Core. |
| 8 | +- **Frontend:** Developed using Next.js/React/TypeScript. |
| 9 | +- **CSS:** Utilizes Tailwind CSS. |
| 10 | + |
| 11 | +## Environment Requirements |
| 12 | + |
| 13 | +- Git |
| 14 | +- .NET SDK 8.0 |
| 15 | +- Node.js >= 20 |
| 16 | +- Visual Studio Code |
| 17 | +- Visual Studio 2022 (optional but recommended) |
| 18 | + |
| 19 | +## Obtaining the Code |
| 20 | + |
| 21 | +First, clone the Chats code repository: |
| 22 | + |
| 23 | +```bash |
| 24 | +git clone https://github.com/sdcb/chats.git |
| 25 | +``` |
| 26 | + |
| 27 | +## Joint Frontend and Backend Development |
| 28 | + |
| 29 | +### Backend Development Guide |
| 30 | + |
| 31 | +1. Use Visual Studio to open the solution: |
| 32 | + |
| 33 | + Locate the `chats/Chats.sln` solution file in the root directory and open it. In Visual Studio, you'll see a website project named `Chats.BE`. |
| 34 | + |
| 35 | +2. Run the project: |
| 36 | + |
| 37 | + - Press F5 to run the project. The default configuration will check if the SQLite database file `chats.db` exists, and if not, it will automatically create it in the `./AppData` directory and initialize the database. |
| 38 | + - The service will run on `http://localhost:5146`, providing API services. If running in development mode (`ASPNETCORE_ENVIRONMENT=Development`), Swagger UI will be available at `http://localhost:5146/swagger`. |
| 39 | + |
| 40 | +3. Configuration file explanation: |
| 41 | + |
| 42 | + The default configuration is located in `appsettings.json`, but it is strongly recommended to manage sensitive information using `userSecrets.json`. This can prevent accidental exposure of sensitive development configurations in the code base. |
| 43 | + |
| 44 | + **Default configuration structure:** |
| 45 | + |
| 46 | + ```json |
| 47 | + { |
| 48 | + "Logging": { |
| 49 | + "LogLevel": { |
| 50 | + "Default": "Information", |
| 51 | + "Microsoft.AspNetCore": "Warning" |
| 52 | + } |
| 53 | + }, |
| 54 | + "AllowedHosts": "*", |
| 55 | + "FE_URL": "http://localhost:3001", |
| 56 | + "ENCRYPTION_PASSWORD": "this is used for encrypt auto increment int id, please set as a random string.", |
| 57 | + "DBType": "sqlite", |
| 58 | + "ConnectionStrings": { |
| 59 | + "ChatsDB": "Data Source=./AppData/chats.db" |
| 60 | + } |
| 61 | + } |
| 62 | + ``` |
| 63 | + |
| 64 | + **Configuration options explanation:** |
| 65 | + |
| 66 | + - `Logging`: Manages log level; defaults to recording information level logs. |
| 67 | + - `AllowedHosts`: Configures allowed host names; `*` accepts all hosts. |
| 68 | + - `FE_URL`: Frontend URL, defaults to `http://localhost:3001`. The frontend can access the backend via CORS, with no extra configuration required for port 3000. |
| 69 | + - `DBType`: Database type, supporting `sqlite` (default), `mssql`, and `postgresql`. |
| 70 | + - `ConnectionStrings:ChatsDB`: Database `ADO.NET` connection string, varying based on `DBType`. |
| 71 | + - `ENCRYPTION_PASSWORD`: Used for encrypting auto-increment integer IDs. In a production environment, it should be set to a random string to avoid direct exposure of IDs. |
| 72 | + |
| 73 | + **Why use integer + encryption instead of GUID?** |
| 74 | + |
| 75 | + Initially, the Chats project used GUIDs, but due to the following two reasons and careful consideration, it was switched to auto-increment integer IDs: |
| 76 | + - GUID fields are larger, taking up more space; |
| 77 | + - GUIDs as clustered indexes can lead to index fragmentation, affecting performance; |
| 78 | + |
| 79 | + |
| 80 | + **Managing sensitive configurations:** |
| 81 | + |
| 82 | + It's not recommended to directly modify configuration items in `appsettings.json`. Instead, use `userSecrets.json` via Visual Studio: |
| 83 | + |
| 84 | + - Visual Studio: Right-click the `Chats.BE` project -> `Manage User Secrets`. |
| 85 | + - CLI: Manage user secrets with the following commands. |
| 86 | + |
| 87 | + ```bash |
| 88 | + dotnet user-secrets init |
| 89 | + dotnet user-secrets set "key" "value" |
| 90 | + dotnet user-secrets list |
| 91 | + ``` |
| 92 | + |
| 93 | + This helps avoid accidentally uploading sensitive information when committing code. |
| 94 | + |
| 95 | +4. Running without Visual Studio: |
| 96 | + |
| 97 | + Navigate to the backend directory: |
| 98 | + |
| 99 | + ```bash |
| 100 | + cd ./chats/src/BE |
| 101 | + dotnet run |
| 102 | + ``` |
| 103 | + |
| 104 | +### Frontend Development Guide |
| 105 | + |
| 106 | +1. Navigate to the frontend directory: |
| 107 | + |
| 108 | + ```bash |
| 109 | + cd ./chats/src/FE |
| 110 | + ``` |
| 111 | + |
| 112 | +2. Create a `.env.local` file and specify the backend URL: |
| 113 | + |
| 114 | + ```bash |
| 115 | + echo "API_URL=http://localhost:5146" > .env.local |
| 116 | + ``` |
| 117 | + |
| 118 | +3. Install dependencies and run the development server: |
| 119 | + |
| 120 | + ```bash |
| 121 | + npm i |
| 122 | + npm run dev |
| 123 | + ``` |
| 124 | + |
| 125 | +After running, the frontend service will listen on `http://localhost:3000`. The backend already supports CORS configuration with no extra setup needed. |
| 126 | + |
| 127 | +## Frontend Only Development |
| 128 | + |
| 129 | +For frontend-focused development scenarios, we provide a pre-deployed backend development environment: |
| 130 | + |
| 131 | +1. Clone the repository: |
| 132 | + |
| 133 | + ```bash |
| 134 | + git clone https://github.com/sdcb/chats.git |
| 135 | + ``` |
| 136 | + |
| 137 | +2. Enter the frontend directory and specify the remote backend: |
| 138 | + |
| 139 | + ```bash |
| 140 | + cd ./chats/src/FE |
| 141 | + echo "API_URL=https://chats-dev.starworks.cc:88" > .env.local |
| 142 | + ``` |
| 143 | + |
| 144 | + This environment already allows cross-origin access behavior from http://localhost:3000. |
| 145 | + |
| 146 | +3. Install dependencies and run: |
| 147 | + |
| 148 | + ```bash |
| 149 | + npm i |
| 150 | + npm run dev |
| 151 | + ``` |
| 152 | + |
| 153 | +### Notes |
| 154 | + |
| 155 | +To simulate a production build process, execute: |
| 156 | + |
| 157 | +```bash |
| 158 | +npm run build |
| 159 | +``` |
| 160 | + |
| 161 | +This command will generate an `./out` folder in the current directory containing all necessary static files. |
| 162 | + |
| 163 | +## Backend Only Development |
| 164 | + |
| 165 | +For backend-focused development scenarios, you can use packaged frontend files: |
| 166 | + |
| 167 | +1. Clone the repository and navigate to the backend directory: |
| 168 | + |
| 169 | + ```bash |
| 170 | + git clone https://github.com/sdcb/chats.git |
| 171 | + cd ./chats/src/BE |
| 172 | + ``` |
| 173 | + |
| 174 | +2. Download and extract frontend static files into `wwwroot`: |
| 175 | + |
| 176 | + **On Linux:** |
| 177 | + |
| 178 | + ```bash |
| 179 | + curl -O https://github.com/sdcb/chats/releases/latest/download/chats-fe.zip |
| 180 | + unzip chats-fe.zip |
| 181 | + cp -r chats-fe/* wwwroot/ |
| 182 | + ``` |
| 183 | + |
| 184 | + **On Windows:** |
| 185 | + |
| 186 | + ```powershell |
| 187 | + Invoke-WebRequest -Uri "https://github.com/sdcb/chats/releases/latest/download/chats-fe.zip" -OutFile "chats-fe.zip" |
| 188 | + Expand-Archive -Path "chats-fe.zip" -DestinationPath "." |
| 189 | + Copy-Item -Path ".\chats-fe\*" -Destination ".\wwwroot" -Recurse -Force |
| 190 | + ``` |
| 191 | + |
| 192 | + ### Note |
| 193 | + 1. I have also uploaded the above https://github.com/sdcb/chats/releases/latest/download/chats-fe.zip to my personal Minio file server at: http://io.starworks.cc:88/chats/latest/chats-fe.zip |
| 194 | + |
| 195 | + If downloading directly from GitHub is too slow, you can use this address instead. |
| 196 | + |
| 197 | + 2. The attached `chats-fe.zip` is automatically generated by GitHub Actions when code is merged into the `main` branch, not triggered for `dev` branch merges. |
| 198 | + |
| 199 | +3. Run the backend: |
| 200 | + |
| 201 | + ```bash |
| 202 | + dotnet run |
| 203 | + ``` |
| 204 | + |
| 205 | + Alternatively, open `Chats.sln` in Visual Studio and run the `Chats.BE` project. |
| 206 | + |
| 207 | +Once running, visiting `http://localhost:5146/login` will directly take you to the Chats login page, realizing a deployment mode where front-end and back-end are not separated. |
| 208 | + |
| 209 | +I hope this guide will assist you in successfully developing the Chats project. If you have any questions, please refer to the documentation in the source code or create an issue at https://github.com/sdcb/chats to receive support. |
0 commit comments