Skip to content

Commit 9e8a7b3

Browse files
AntoLCAntoLC
committed
📝(project) add troubleshoot doc
Add a troubleshooting document to help users resolve common issues.
1 parent 05db9c8 commit 9e8a7b3

File tree

2 files changed

+195
-0
lines changed

2 files changed

+195
-0
lines changed

‎CHANGELOG.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ and this project adheres to
1111
### Added
1212

1313
- ✨(frontend) add customization for translations #857
14+
- 📝(project) add troubleshoot doc #1066
1415

1516
### Changed
1617

‎docs/troubleshoot.md

Lines changed: 194 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,194 @@
1+
# Troubleshooting Guide
2+
3+
## Line Ending Issues on Windows (LF/CRLF)
4+
5+
### Problem Description
6+
7+
This project uses **LF (Line Feed: `\n`) line endings** exclusively. Windows users may encounter issues because:
8+
9+
- **Windows** defaults to CRLF (Carriage Return + Line Feed: `\r\n`) for line endings
10+
- **This project** uses LF line endings for consistency across all platforms
11+
- **Git** may automatically convert line endings, causing conflicts or build failures
12+
13+
### Common Symptoms
14+
15+
- Git shows files as modified even when no changes were made
16+
- Error messages like "warning: LF will be replaced by CRLF"
17+
- Build failures or linting errors due to line ending mismatches
18+
19+
### Solutions for Windows Users
20+
21+
#### Configure Git to Preserve LF (Recommended)
22+
23+
Configure Git to NOT convert line endings and preserve LF:
24+
25+
```bash
26+
git config core.autocrlf false
27+
git config core.eol lf
28+
```
29+
30+
This tells Git to:
31+
- Never convert line endings automatically
32+
- Always use LF for line endings in working directory
33+
34+
35+
#### Fix Existing Repository with Wrong Line Endings
36+
37+
If you already have CRLF line endings in your local repository, the **best approach** is to configure Git properly and clone the project again:
38+
39+
1. **Configure Git first**:
40+
```bash
41+
git config --global core.autocrlf false
42+
git config --global core.eol lf
43+
```
44+
45+
2. **Clone the project fresh** (recommended):
46+
```bash
47+
# Navigate to parent directory
48+
cd ..
49+
50+
# Remove current repository (backup your changes first!)
51+
rm -rf docs
52+
53+
# Clone again with correct line endings
54+
git clone [email protected]:suitenumerique/docs.git
55+
```
56+
57+
**Alternative**: If you have uncommitted changes and cannot re-clone:
58+
59+
1. **Backup your changes**:
60+
```bash
61+
git add .
62+
git commit -m "Save changes before fixing line endings"
63+
```
64+
65+
2. **Remove all files from Git's index**:
66+
```bash
67+
git rm --cached -r .
68+
```
69+
70+
3. **Reset Git configuration** (if not done globally):
71+
```bash
72+
git config core.autocrlf false
73+
git config core.eol lf
74+
```
75+
76+
4. **Re-add all files** (Git will use LF line endings):
77+
```bash
78+
git add .
79+
```
80+
81+
5. **Commit the changes**:
82+
```bash
83+
git commit -m "✏️(project) Fix line endings to LF"
84+
```
85+
86+
## Minio Permission Issues on Windows
87+
88+
### Problem Description
89+
90+
On Windows, you may encounter permission-related errors when running Minio in development mode with Docker Compose. This typically happens because:
91+
92+
- **Windows file permissions** don't map well to Unix-style user IDs used in Docker containers
93+
- **Docker Desktop** may have issues with user mapping when using the `DOCKER_USER` environment variable
94+
- **Minio container** fails to start or access volumes due to permission conflicts
95+
96+
### Common Symptoms
97+
98+
- Minio container fails to start with permission denied errors
99+
- Error messages related to file system permissions in Minio logs
100+
- Unable to create or access buckets in the development environment
101+
- Docker Compose showing Minio service as unhealthy or exited
102+
103+
### Solution for Windows Users
104+
105+
If you encounter Minio permission issues on Windows, you can temporarily disable user mapping for the Minio service:
106+
107+
1. **Open the `compose.yml` file**
108+
109+
2. **Comment out the user directive** in the `minio` service section:
110+
```yaml
111+
minio:
112+
# user: ${DOCKER_USER:-1000} # Comment this line on Windows if permission issues occur
113+
image: minio/minio
114+
environment:
115+
- MINIO_ROOT_USER=impress
116+
- MINIO_ROOT_PASSWORD=password
117+
# ... rest of the configuration
118+
```
119+
120+
3. **Restart the services**:
121+
```bash
122+
make run
123+
```
124+
125+
### Why This Works
126+
127+
- Commenting out the `user` directive allows the Minio container to run with its default user
128+
- This bypasses Windows-specific permission mapping issues
129+
- The container will have the necessary permissions to access and manage the mounted volumes
130+
131+
### Note
132+
133+
This is a **development-only workaround**. In production environments, proper user mapping and security considerations should be maintained according to your deployment requirements.
134+
135+
## Frontend File Watching Issues on Windows
136+
137+
### Problem Description
138+
139+
Windows users may experience issues with file watching in the frontend-development container. This typically happens because:
140+
141+
- **Docker on Windows** has known limitations with file change detection
142+
- **Node.js file watchers** may not detect changes properly on Windows filesystem
143+
- **Hot reloading** fails to trigger when files are modified
144+
145+
### Common Symptoms
146+
147+
- Changes to frontend code aren't detected automatically
148+
- Hot module replacement doesn't work as expected
149+
- Need to manually restart the frontend container after code changes
150+
- Console shows no reaction when saving files
151+
152+
### Solution: Enable WATCHPACK_POLLING
153+
154+
Add the `WATCHPACK_POLLING=true` environment variable to the frontend-development service in your local environment:
155+
156+
1. **Modify the `compose.yml` file** by adding the environment variable to the frontend-development service:
157+
158+
```yaml
159+
frontend-development:
160+
user: "${DOCKER_USER:-1000}"
161+
build:
162+
context: .
163+
dockerfile: ./src/frontend/Dockerfile
164+
target: impress-dev
165+
args:
166+
API_ORIGIN: "http://localhost:8071"
167+
PUBLISH_AS_MIT: "false"
168+
SW_DEACTIVATED: "true"
169+
image: impress:frontend-development
170+
environment:
171+
- WATCHPACK_POLLING=true # Add this line for Windows users
172+
volumes:
173+
- ./src/frontend:/home/frontend
174+
- /home/frontend/node_modules
175+
- /home/frontend/apps/impress/node_modules
176+
ports:
177+
- "3000:3000"
178+
```
179+
180+
2. **Restart your containers**:
181+
```bash
182+
make run
183+
```
184+
185+
### Why This Works
186+
187+
- `WATCHPACK_POLLING=true` forces the file watcher to use polling instead of filesystem events
188+
- Polling periodically checks for file changes rather than relying on OS-level file events
189+
- This is more reliable on Windows but slightly increases CPU usage
190+
- Changes to your frontend code should now be detected properly, enabling hot reloading
191+
192+
### Note
193+
194+
This setting is primarily needed for Windows users. Linux and macOS users typically don't need this setting as file watching works correctly by default on those platforms.

0 commit comments

Comments
 (0)