Skip to content

Commit 15f20a7

Browse files
olexii4olexii4
committed
feat: add multi-architecture build support
Added build-multiarch.sh script for building multi-architecture Docker images supporting AMD64 and ARM64 platforms. Changes: - Added run/build-multiarch.sh: Dedicated script for multi-arch builds - Docker Buildx support for parallel multi-platform builds - Podman manifest support for multi-arch images - Configurable platforms via PLATFORMS env var - Updated run/patch.sh: Simplified to single-arch build + patch - Can now accept CHE_DASHBOARD_IMAGE to skip build and just patch - Enhanced scripts/container_tool.sh: Added 'detect' command - Returns 'docker' or 'podman' based on available engine - Added run/MULTIARCH_BUILD.md: Comprehensive multi-arch documentation - Added run/README.md: Quick reference for all run scripts Usage: # Multi-arch build ./run/build-multiarch.sh # Single-arch build + patch ./run/patch.sh # Patch with existing image CHE_DASHBOARD_IMAGE=quay.io/user/che-dashboard:tag ./run/patch.sh Signed-off-by: Oleksii Orel <[email protected]>
1 parent 65257c6 commit 15f20a7

File tree

5 files changed

+570
-36
lines changed

5 files changed

+570
-36
lines changed

‎run/MULTIARCH_BUILD.md‎

Lines changed: 205 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,205 @@
1+
# Multi-Architecture Build Guide
2+
3+
## Overview
4+
5+
The `build-multiarch.sh` script builds Docker images for multiple architectures (AMD64 and ARM64) and pushes them to a container registry.
6+
7+
## Prerequisites
8+
9+
### For Docker:
10+
- Docker with buildx support (Docker 19.03+)
11+
- Enable experimental features in Docker (usually enabled by default in newer versions)
12+
13+
### For Podman:
14+
- Podman 3.0+ with manifest support
15+
- QEMU user-mode emulation for cross-platform builds:
16+
```bash
17+
# On macOS
18+
brew install qemu
19+
20+
# On Linux
21+
sudo apt-get install qemu-user-static # Debian/Ubuntu
22+
sudo dnf install qemu-user-static # Fedora/RHEL
23+
```
24+
25+
## Usage
26+
27+
### Multi-Architecture Build (Default)
28+
29+
Build for both AMD64 and ARM64:
30+
31+
```bash
32+
export IMAGE_REGISTRY_HOST=quay.io
33+
export IMAGE_REGISTRY_USER_NAME=your-username
34+
./run/build-multiarch.sh
35+
```
36+
37+
### Custom Platforms
38+
39+
Specify custom platforms:
40+
41+
```bash
42+
export IMAGE_REGISTRY_HOST=quay.io
43+
export IMAGE_REGISTRY_USER_NAME=your-username
44+
export PLATFORMS=linux/amd64,linux/arm64,linux/ppc64le
45+
./run/build-multiarch.sh
46+
```
47+
48+
### Build Only AMD64
49+
50+
```bash
51+
export IMAGE_REGISTRY_HOST=quay.io
52+
export IMAGE_REGISTRY_USER_NAME=your-username
53+
export PLATFORMS=linux/amd64
54+
./run/build-multiarch.sh
55+
```
56+
57+
### Build Only ARM64
58+
59+
```bash
60+
export IMAGE_REGISTRY_HOST=quay.io
61+
export IMAGE_REGISTRY_USER_NAME=your-username
62+
export PLATFORMS=linux/arm64
63+
./run/build-multiarch.sh
64+
```
65+
66+
### Build and Patch CheCluster
67+
68+
After building a multi-arch image, patch the CheCluster:
69+
70+
```bash
71+
# Build multi-arch image
72+
export IMAGE_REGISTRY_HOST=quay.io
73+
export IMAGE_REGISTRY_USER_NAME=your-username
74+
./run/build-multiarch.sh
75+
76+
# Patch CheCluster with the built image
77+
export CHE_DASHBOARD_IMAGE=quay.io/your-username/che-dashboard:TAG
78+
./run/patch.sh
79+
```
80+
81+
## Environment Variables
82+
83+
| Variable | Description | Default | Required |
84+
|----------|-------------|---------|----------|
85+
| `IMAGE_REGISTRY_HOST` | Container registry host | - | Yes |
86+
| `IMAGE_REGISTRY_USER_NAME` | Registry username/namespace | - | Yes |
87+
| `PLATFORMS` | Comma-separated list of platforms | `linux/amd64,linux/arm64` | No |
88+
| `IMAGE_TAG` | Custom image tag | `branch_timestamp` | No |
89+
90+
## How It Works
91+
92+
### Docker Buildx
93+
94+
1. Creates or reuses a buildx builder named `multiarch-builder`
95+
2. Bootstraps the builder with support for specified platforms
96+
3. Builds and pushes the multi-arch image in a single command
97+
4. The resulting image is a manifest list that contains images for all specified platforms
98+
99+
### Podman
100+
101+
1. Creates a manifest for the image
102+
2. Builds separate images for each platform
103+
3. Adds each platform-specific image to the manifest
104+
4. Pushes the manifest to the registry
105+
106+
## Verification
107+
108+
After building, verify the multi-arch image:
109+
110+
### Using Docker:
111+
```bash
112+
docker buildx imagetools inspect ${IMAGE_REGISTRY_HOST}/${IMAGE_REGISTRY_USER_NAME}/che-dashboard:${TAG}
113+
```
114+
115+
### Using Podman:
116+
```bash
117+
podman manifest inspect ${IMAGE_REGISTRY_HOST}/${IMAGE_REGISTRY_USER_NAME}/che-dashboard:${TAG}
118+
```
119+
120+
### Using Skopeo:
121+
```bash
122+
skopeo inspect docker://${IMAGE_REGISTRY_HOST}/${IMAGE_REGISTRY_USER_NAME}/che-dashboard:${TAG}
123+
```
124+
125+
## Troubleshooting
126+
127+
### Docker: "multiple platforms feature is currently not supported for docker driver"
128+
129+
Switch to the buildx builder:
130+
```bash
131+
docker buildx create --name multiarch-builder --use
132+
docker buildx inspect --bootstrap
133+
```
134+
135+
### Podman: "Error: command "manifest" is not supported with remote Podman"
136+
137+
Make sure you're using local Podman, not remote:
138+
```bash
139+
unset CONTAINER_HOST
140+
```
141+
142+
### QEMU: "exec format error"
143+
144+
Install QEMU user-mode emulation:
145+
```bash
146+
# Linux
147+
docker run --rm --privileged multiarch/qemu-user-static --reset -p yes
148+
149+
# macOS
150+
brew install qemu
151+
```
152+
153+
### Build is very slow
154+
155+
Cross-platform builds using QEMU emulation are slower than native builds. This is expected. For faster builds:
156+
- Build on native hardware for each architecture
157+
- Use CI/CD with native runners for each architecture
158+
- Use cloud build services that support multi-arch
159+
160+
## CI/CD Integration
161+
162+
Example GitHub Actions workflow:
163+
164+
```yaml
165+
name: Multi-Arch Build
166+
167+
on:
168+
push:
169+
branches: [ main ]
170+
171+
jobs:
172+
build:
173+
runs-on: ubuntu-latest
174+
steps:
175+
- uses: actions/checkout@v3
176+
177+
- name: Set up QEMU
178+
uses: docker/setup-qemu-action@v2
179+
180+
- name: Set up Docker Buildx
181+
uses: docker/setup-buildx-action@v2
182+
183+
- name: Login to Registry
184+
run: echo "${{ secrets.REGISTRY_PASSWORD }}" | docker login ${{ secrets.REGISTRY_HOST }} -u ${{ secrets.REGISTRY_USER }} --password-stdin
185+
186+
- name: Build and Push
187+
env:
188+
IMAGE_REGISTRY_HOST: ${{ secrets.REGISTRY_HOST }}
189+
IMAGE_REGISTRY_USER_NAME: ${{ secrets.REGISTRY_USER }}
190+
PLATFORMS: linux/amd64,linux/arm64
191+
run: ./run/build-multiarch.sh
192+
```
193+
194+
## Performance Tips
195+
196+
1. **Use BuildKit cache**: Enable BuildKit cache mounts in your Dockerfile
197+
2. **Layer caching**: Structure your Dockerfile to maximize layer reuse
198+
3. **Parallel builds**: For Podman, you can build platforms in parallel using background jobs
199+
4. **Registry mirrors**: Use registry mirrors to speed up base image pulls
200+
201+
## Related Documentation
202+
203+
- [Docker Buildx Documentation](https://docs.docker.com/buildx/working-with-buildx/)
204+
- [Podman Manifest Documentation](https://docs.podman.io/en/latest/markdown/podman-manifest.1.html)
205+
- [OCI Image Spec](https://github.com/opencontainers/image-spec)

‎run/README.md‎

Lines changed: 170 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,170 @@
1+
# Dashboard Build and Deployment Scripts
2+
3+
## Overview
4+
5+
This directory contains scripts for building, testing, and deploying the Eclipse Che dashboard.
6+
7+
## Scripts
8+
9+
### `patch.sh` - Build and Deploy Dashboard Image
10+
11+
Builds a single-architecture image, pushes it, and patches the CheCluster.
12+
13+
**Quick Start:**
14+
15+
```bash
16+
export IMAGE_REGISTRY_HOST=quay.io
17+
export IMAGE_REGISTRY_USER_NAME=your-username
18+
./run/patch.sh
19+
```
20+
21+
**Use existing image (skip build):**
22+
23+
```bash
24+
export CHE_DASHBOARD_IMAGE=quay.io/username/che-dashboard:tag
25+
./run/patch.sh
26+
```
27+
28+
**Environment Variables:**
29+
30+
| Variable | Description | Default | Required |
31+
|----------|-------------|---------|----------|
32+
| `IMAGE_REGISTRY_HOST` | Container registry host | - | Yes (if building) |
33+
| `IMAGE_REGISTRY_USER_NAME` | Registry username | - | Yes (if building) |
34+
| `CHE_NAMESPACE` | Kubernetes namespace | `eclipse-che` | No |
35+
| `CHE_DASHBOARD_IMAGE` | Use existing image | - | No |
36+
37+
---
38+
39+
### `build-multiarch.sh` - Multi-Architecture Build
40+
41+
Builds and pushes multi-architecture images (AMD64 + ARM64).
42+
43+
**Quick Start:**
44+
45+
```bash
46+
export IMAGE_REGISTRY_HOST=quay.io
47+
export IMAGE_REGISTRY_USER_NAME=your-username
48+
./run/build-multiarch.sh
49+
```
50+
51+
**Build for specific platforms:**
52+
53+
```bash
54+
export PLATFORMS=linux/amd64,linux/arm64
55+
./run/build-multiarch.sh
56+
```
57+
58+
**Build and patch:**
59+
60+
```bash
61+
# Build multi-arch
62+
./run/build-multiarch.sh
63+
64+
# Patch CheCluster
65+
export CHE_DASHBOARD_IMAGE=quay.io/username/che-dashboard:tag
66+
./run/patch.sh
67+
```
68+
69+
**Environment Variables:**
70+
71+
| Variable | Description | Default | Required |
72+
|----------|-------------|---------|----------|
73+
| `IMAGE_REGISTRY_HOST` | Container registry host | - | Yes |
74+
| `IMAGE_REGISTRY_USER_NAME` | Registry username | - | Yes |
75+
| `PLATFORMS` | Platforms to build | `linux/amd64,linux/arm64` | No |
76+
| `IMAGE_TAG` | Custom image tag | `branch_timestamp` | No |
77+
78+
📖 See [MULTIARCH_BUILD.md](./MULTIARCH_BUILD.md) for detailed documentation.
79+
80+
---
81+
82+
### `local-run.sh` - Run Dashboard Locally
83+
84+
Run the dashboard locally for development.
85+
86+
```bash
87+
./run/local-run.sh
88+
```
89+
90+
---
91+
92+
### `prepare-local-run.sh` - Prepare Local Development
93+
94+
Prepare the environment for local dashboard development.
95+
96+
```bash
97+
./run/prepare-local-run.sh
98+
```
99+
100+
---
101+
102+
### `revert-local-run.sh` - Revert Local Changes
103+
104+
Revert changes made by local development scripts.
105+
106+
```bash
107+
./run/revert-local-run.sh
108+
```
109+
110+
---
111+
112+
## Multi-Architecture Build
113+
114+
For multi-architecture builds supporting AMD64 and ARM64:
115+
116+
```bash
117+
export IMAGE_REGISTRY_HOST=quay.io
118+
export IMAGE_REGISTRY_USER_NAME=your-username
119+
./run/build-multiarch.sh
120+
```
121+
122+
### Prerequisites
123+
124+
**For Docker:**
125+
- Docker 19.03+ with buildx support
126+
127+
```bash
128+
# Install QEMU (if needed for cross-platform builds)
129+
docker run --rm --privileged multiarch/qemu-user-static --reset -p yes
130+
```
131+
132+
**For Podman:**
133+
- Podman 3.0+ with manifest support
134+
135+
```bash
136+
# On macOS
137+
brew install qemu
138+
139+
# On Linux
140+
sudo apt-get install qemu-user-static # Debian/Ubuntu
141+
sudo dnf install qemu-user-static # Fedora/RHEL
142+
```
143+
144+
### Verification
145+
146+
Check your multi-arch image:
147+
148+
```bash
149+
# Docker
150+
docker buildx imagetools inspect quay.io/username/che-dashboard:TAG
151+
152+
# Skopeo
153+
skopeo inspect docker://quay.io/username/che-dashboard:TAG
154+
```
155+
156+
---
157+
158+
## Documentation
159+
160+
- [Multi-Architecture Build Guide](./MULTIARCH_BUILD.md) - Detailed multi-arch documentation
161+
- [Docker Buildx](https://docs.docker.com/buildx/working-with-buildx/)
162+
- [Podman Manifest](https://docs.podman.io/en/latest/markdown/podman-manifest.1.html)
163+
164+
---
165+
166+
## Support
167+
168+
For issues or questions:
169+
- GitHub Issues: https://github.com/eclipse-che/che-dashboard/issues
170+
- Slack: #eclipse-che on Kubernetes Slack

0 commit comments

Comments
 (0)