diff options
Diffstat (limited to 'docker_readme.md')
| -rw-r--r-- | docker_readme.md | 173 |
1 files changed, 173 insertions, 0 deletions
diff --git a/docker_readme.md b/docker_readme.md new file mode 100644 index 0000000..5b3c8cd --- /dev/null +++ b/docker_readme.md @@ -0,0 +1,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 +``` + |