mirror of
https://github.com/kevinveenbirkenbach/computer-playbook.git
synced 2025-07-17 05:54:24 +02:00
125 lines
3.6 KiB
Markdown
125 lines
3.6 KiB
Markdown
# Docker Build Guide 🚢
|
||
|
||
This guide explains how to build the **CyMaIS** Docker image with advanced options to avoid common issues (e.g. mirror timeouts) and control build caching.
|
||
|
||
---
|
||
|
||
## 1. Enable BuildKit (Optional but Recommended)
|
||
|
||
Modern versions of Docker support **BuildKit**, which speeds up build processes and offers better caching.
|
||
|
||
```bash
|
||
# On your host, enable BuildKit for the current shell session:
|
||
export DOCKER_BUILDKIT=1
|
||
```
|
||
|
||
> **Note:** You only need to set this once per terminal session.
|
||
|
||
---
|
||
|
||
## 2. Build Arguments Explained
|
||
|
||
When you encounter errors like:
|
||
|
||
```text
|
||
:: Synchronizing package databases...
|
||
error: failed retrieving file 'core.db' from geo.mirror.pkgbuild.com : Connection timed out after 10002 milliseconds
|
||
error: failed to synchronize all databases (failed to retrieve some files)
|
||
```
|
||
|
||
it usually means the default container network cannot reach certain Arch Linux mirrors. To work around this, use:
|
||
|
||
* `--network=host`
|
||
Routes all build-time network traffic through your host’s network stack.
|
||
|
||
* `--no-cache`
|
||
Forces a fresh build of every layer by ignoring Docker’s layer cache. Useful if you suspect stale cache entries.
|
||
|
||
---
|
||
|
||
## 3. Recommended Build Command
|
||
|
||
```bash
|
||
# 1. (Optional) Enable BuildKit
|
||
export DOCKER_BUILDKIT=1
|
||
|
||
# 2. Build with host networking and no cache
|
||
docker build \
|
||
--network=host \
|
||
--no-cache \
|
||
-t cymais:latest \
|
||
.
|
||
```
|
||
|
||
**Flags:**
|
||
|
||
* `--network=host`
|
||
Ensures all `pacman -Syu` and other network calls hit your host network directly—eliminating mirror connection timeouts.
|
||
|
||
* `--no-cache`
|
||
Guarantees that changes to package lists or dependencies are picked up immediately by rebuilding every layer.
|
||
|
||
* `-t cymais:latest`
|
||
Tags the resulting image as `cymais:latest`.
|
||
|
||
---
|
||
|
||
## 4. Running the Container
|
||
|
||
Once built, you can run CyMaIS as usual:
|
||
|
||
```bash
|
||
docker run --rm -it \
|
||
-v "$(pwd)":/opt/cymais \
|
||
-w /opt/cymais \
|
||
cymais:latest --help
|
||
```
|
||
|
||
Mount any host directory into `/opt/cymais/logs` to persist logs across runs.
|
||
|
||
---
|
||
|
||
## 5. Further Troubleshooting
|
||
|
||
* **Mirror selection:** If you still see slow or unreachable mirrors, consider customizing `/etc/pacman.d/mirrorlist` in a local Docker stage or on your host to prioritize faster mirrors.
|
||
|
||
* **Firewall or VPN:** Ensure your host’s firewall or VPN allows outgoing connections on port 443/80 to Arch mirror servers.
|
||
|
||
* **Docker daemon config:** On some networks, you may need to configure Docker’s daemon proxy settings under `/etc/docker/daemon.json`.
|
||
|
||
## 6. Live Development via Volume Mount
|
||
|
||
The CyMaIS installation inside the container always resides at:
|
||
|
||
```
|
||
/root/Repositories/github.com/kevinveenbirkenbach/cymais
|
||
```
|
||
|
||
To apply code changes without rebuilding the image, mount your local installation directory into that static path:
|
||
|
||
```bash
|
||
# 1. Determine the CyMaIS install path on your host
|
||
CMAIS_PATH=$(pkgmgr path cymais)
|
||
|
||
# 2. Launch the container with a bind mount:
|
||
docker run --rm -it \
|
||
-v "${CMAIS_PATH}:/root/Repositories/github.com/kevinveenbirkenbach/cymais" \
|
||
-w "/root/Repositories/github.com/kevinveenbirkenbach/cymais" \
|
||
cymais:latest make build
|
||
```
|
||
|
||
Or, to test the CLI help interactively:
|
||
|
||
```bash
|
||
docker run --rm -it \
|
||
-v "${CMAIS_PATH}:/root/Repositories/github.com/kevinveenbirkenbach/cymais" \
|
||
-w "/root/Repositories/github.com/kevinveenbirkenbach/cymais" \
|
||
cymais:latest --help
|
||
```
|
||
|
||
Any edits you make in `${CMAIS_PATH}` on your host are immediately reflected inside the container, eliminating the need for repeated `docker build` cycles.
|
||
|
||
---
|
||
|
||
With these options, your Docker builds should complete reliably, even in restrictive network environments. Happy building! 🚀
|