blob: 5b3c8cd4e64cf3e678f71e840e186688a6adaa0b (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
|
# Docker Development Setup
This guide explains how to run the Bicycle Wheel Circumference app inside a
Docker container with **live reload** — edit files on your host and see changes
instantly in the browser, even from another PC on your network.
---
### Prerequisites
| Tool | Minimum version | Check with |
| -------------- | --------------- | --------------------- |
| Docker Engine | 20.10+ | `docker --version` |
| Docker Compose | 2.0+ (V2) | `docker compose version` |
> **Note:** On most modern Docker Desktop / Docker Engine installs the
> `docker compose` (V2) sub-command is included. If you only have the
> legacy `docker-compose` binary, the commands below work the same way —
> just replace `docker compose` with `docker-compose`.
---
### How it works
```
┌──────────────────────────────────────────────────────────┐
│ Host machine │
│ │
│ project root ──bind-mount──▸ /app (container) │
│ (your editor) │ │
│ ├─ npm install │
│ └─ vite dev (0.0.0.0) │
│ │ │
│ http://localhost:5173 ◂─────────────┘ │
│ http://<host-ip>:5173 ◂─── other PCs on LAN │
└──────────────────────────────────────────────────────────┘
```
* The project directory is **mounted** into the container, so every file
change on the host is visible inside Docker immediately.
* Vite’s dev server uses **polling** (`usePolling: true`) to detect changes
on bind-mounted volumes (native filesystem events don’t cross the Docker
boundary reliably).
* The container uses the official **Node.js 25 Alpine** image, keeping the
image small and Node pre-installed with no extra tooling.
---
### Quick start
#### 1. Clone the repository
```bash
git clone <repo-url>
cd tirecalc
```
#### 2. Build the Docker image
This pulls the Node.js Alpine base image and copies in the entrypoint
script. You only need to rebuild when the `Dockerfile` itself changes.
```bash
docker compose build
```
#### 3. Start the dev server
```bash
docker compose up
```
The first run will also execute `npm install` inside the container.
Once you see output like:
```
VITE v7.x.x ready in XXX ms
➜ Local: http://localhost:5173/
➜ Network: http://0.0.0.0:5173/
```
the app is ready.
#### 4. Open in your browser
| From where | URL |
| -------------------- | -------------------------------- |
| Same machine | `http://localhost:5173` |
| Another PC on LAN | `http://<host-ip>:5173` |
> Replace `<host-ip>` with the IP address of the machine running Docker.
> You can find it with `ip addr` (Linux) or `ipconfig` (Windows).
#### 5. Edit files and see live reload
Open any file under `src/` in your editor on the **host** machine. When you
save, Vite’s HMR (Hot Module Replacement) will push the update to every
connected browser tab automatically.
---
### Useful commands
| Action | Command |
| ----------------------------------- | ------------------------------------ |
| Start in background (detached) | `docker compose up -d` |
| View logs while detached | `docker compose logs -f` |
| Stop the container | `docker compose down` |
| Rebuild after Dockerfile changes | `docker compose build` |
| Rebuild and start in one step | `docker compose up --build` |
| Open a shell inside the container | `docker compose exec dev sh` |
| Run a one-off npm command | `docker compose exec dev npm <cmd>` |
| Remove anonymous volumes (clean) | `docker compose down -v` |
---
### Changing the Node.js version
1. Update the `FROM` line in the `Dockerfile` to the desired major version:
```dockerfile
FROM node:25-alpine
```
2. Rebuild the image:
```bash
docker compose build --no-cache
```
3. Start the container again:
```bash
docker compose up
```
> **Tip:** You can pin an exact version (e.g. `node:25.8.0-alpine`) if you
> need a specific patch release.
---
### Troubleshooting
**Hot reload not working?**
Make sure `vite.config.ts` has `server.watch.usePolling` set to `true`.
This is already configured in the repo. If you still see stale content, try
a hard-refresh (`Ctrl-Shift-R`) or restart the container.
**Port 5173 already in use?**
Either stop the process occupying the port, or change the mapping in
`docker-compose.yml`:
```yaml
ports:
- "3000:5173" # host:container
```
Then access the app at `http://localhost:3000`.
**Permission errors on node_modules?**
The container runs as root by default. If your host user doesn’t match,
you can run `docker compose down -v` to remove the anonymous
`node_modules` volume and let it be recreated.
**Cannot access from another PC on the network?**
Verify that no firewall on the Docker host is blocking port 5173. On Linux
you can temporarily open it with:
```bash
sudo ufw allow 5173/tcp
```
|
