Skip to content

Commit 6c79902

Browse files
snowdreamsnowdream
committed
docs: sync README from devcontainers1
1 parent a678560 commit 6c79902

2 files changed

Lines changed: 77 additions & 555 deletions

File tree

‎README.md‎

Lines changed: 40 additions & 279 deletions
Original file line numberDiff line numberDiff line change
@@ -1,328 +1,89 @@
1-
# Base
1+
# DevContainers
22

3-
![Docker Image Version](https://img.shields.io/docker/v/snowdreamtech/base)
4-
![Docker Image Size](https://img.shields.io/docker/image-size/snowdreamtech/base/latest)
5-
![Docker Pulls](https://img.shields.io/docker/pulls/snowdreamtech/base)
6-
![Docker Stars](https://img.shields.io/docker/stars/snowdreamtech/base)
3+
![Docker Image Version](https://img.shields.io/docker/v/snowdreamtech/devcontainers)
4+
![Docker Image Size](https://img.shields.io/docker/image-size/snowdreamtech/devcontainers/latest)
5+
![Docker Pulls](https://img.shields.io/docker/pulls/snowdreamtech/devcontainers)
6+
![Docker Stars](https://img.shields.io/docker/stars/snowdreamtech/devcontainers)
77

8-
Docker base template providing standardized container foundations with flexible entrypoint systems, multi-architecture support, and consistent configuration patterns across Alpine, Debian, and Rocky Linux distributions.
8+
Docker Image packaging for DevContainers. (amd64, arm64)
99

10-
## Overview
10+
# Usage
1111

12-
The Docker base template serves as a foundational starting point for building containerized applications. It provides:
12+
To help you get started creating a container from this image you can either use docker-compose or the docker cli.
1313

14-
- **Standardized Dockerfiles** with OCI annotations and best practices
15-
- **Flexible entrypoint system** supporting custom initialization scripts
16-
- **Consistent environment variable configuration** across all variants
17-
- **Multi-architecture support** for diverse hardware platforms
18-
- **User/group management** with PUID/PGID support for permission handling
19-
- **Three distribution variants**: Alpine (lightweight), Debian (default/widely-compatible), Rocky (enterprise)
14+
## Docker Cli
2015

21-
## Quick Start
22-
23-
```bash
24-
# Pull and run the default Debian variant
25-
docker pull snowdreamtech/base:debian
26-
docker run -d --name=base -e TZ=Asia/Shanghai snowdreamtech/base:debian
27-
28-
# Or use docker-compose
29-
docker-compose up -d
30-
```
31-
32-
## Distribution Variants
33-
34-
### Debian (Default)
35-
36-
The recommended variant for most use cases, providing wide compatibility and extensive package availability.
37-
38-
```bash
39-
docker run -d \
40-
--name=base \
41-
-e TZ=Asia/Shanghai \
42-
--restart unless-stopped \
43-
snowdreamtech/base:debian
44-
```
45-
46-
**Supported Architectures**: i386, amd64, arm32v5, arm32v7, arm64, mips64le, ppc64le, s390x
47-
48-
**Base Image**: `snowdreamtech/debian:13.5.0`
49-
50-
### Alpine
51-
52-
Lightweight variant optimized for minimal image size and fast startup times.
16+
### Simple
5317

5418
```bash
5519
docker run -d \
56-
--name=base \
20+
--name=devcontainers \
5721
-e TZ=Asia/Shanghai \
5822
--restart unless-stopped \
59-
snowdreamtech/base:alpine
23+
snowdreamtech/devcontainers:latest
6024
```
6125

62-
**Supported Architectures**: i386, amd64, arm32v6, arm32v7, arm64, ppc64le, riscv64, s390x
63-
64-
**Base Image**: `snowdreamtech/alpine:3.24.0`
65-
66-
### Rocky
67-
68-
Enterprise-focused variant based on Rocky Linux, ideal for production environments requiring RHEL compatibility.
26+
### Advance
6927

7028
```bash
7129
docker run -d \
72-
--name=base \
30+
--name=devcontainers \
7331
-e TZ=Asia/Shanghai \
32+
-v /path/to/data:/path/to/data \
7433
--restart unless-stopped \
75-
snowdreamtech/base:rocky
76-
```
77-
78-
**Supported Architectures**: i386, amd64, arm32v5, arm32v7, arm64, mips64le, ppc64le, s390x
79-
80-
**Base Image**: `snowdreamtech/rocky:10.2.0`
81-
82-
## Build Instructions
83-
84-
### Single Architecture Build
85-
86-
```bash
87-
# Build Debian variant
88-
docker build -t snowdreamtech/base:debian ./docker/debian/
89-
90-
# Build Alpine variant
91-
docker build -t snowdreamtech/base:alpine ./docker/alpine/
92-
93-
# Build Rocky variant
94-
docker build -t snowdreamtech/base:rocky ./docker/rocky/
95-
```
96-
97-
### Multi-Architecture Build
98-
99-
Build images for multiple architectures using `docker buildx`:
100-
101-
```bash
102-
# Create and use a buildx builder
103-
docker buildx create --use --name build --node build --driver-opt network=host
104-
105-
# Build Debian for multiple architectures
106-
docker buildx build \
107-
--platform=linux/386,linux/amd64,linux/arm/v5,linux/arm/v7,linux/arm64,linux/mips64le,linux/ppc64le,linux/s390x \
108-
-t snowdreamtech/base:debian \
109-
./docker/debian/ \
110-
--push
111-
112-
# Build Alpine for multiple architectures
113-
docker buildx build \
114-
--platform=linux/386,linux/amd64,linux/arm/v6,linux/arm/v7,linux/arm64,linux/ppc64le,linux/riscv64,linux/s390x \
115-
-t snowdreamtech/base:alpine \
116-
./docker/alpine/ \
117-
--push
118-
119-
# Build Rocky for multiple architectures
120-
docker buildx build \
121-
--platform=linux/386,linux/amd64,linux/arm/v5,linux/arm/v7,linux/arm64,linux/mips64le,linux/ppc64le,linux/s390x \
122-
-t snowdreamtech/base:rocky \
123-
./docker/rocky/ \
124-
--push
34+
snowdreamtech/devcontainers:latest
12535
```
12636

127-
## Environment Variables
128-
129-
All variants support the following environment variables for runtime configuration:
130-
131-
| Variable | Default | Description |
132-
|----------|---------|-------------|
133-
| `KEEPALIVE` | `0` | Keep container running (1=enabled, 0=disabled) |
134-
| `CAP_NET_BIND_SERVICE` | `0` | Enable binding to privileged ports (<1024) |
135-
| `LANG` | `C.UTF-8` | Locale setting for UTF-8 character support |
136-
| `UMASK` | `022` | Default file creation mask |
137-
| `DEBUG` | `false` | Enable debug output in entrypoint scripts |
138-
| `PGID` | `0` | Primary group ID for custom user creation |
139-
| `PUID` | `0` | User ID for custom user creation |
140-
| `USER` | `root` | Username for custom user creation |
141-
| `WORKDIR` | `/root` | Working directory path |
142-
| `TZ` | - | Timezone (e.g., `Asia/Shanghai`, `America/New_York`) |
143-
144-
**Debian-specific**:
145-
146-
| Variable | Default | Description |
147-
|----------|---------|-------------|
148-
| `DEBIAN_FRONTEND` | `noninteractive` | Debian package installation mode |
37+
## Docker Compose
14938

150-
### Custom User Creation
151-
152-
Create a non-root user with specific UID/GID at build time:
153-
154-
```bash
155-
docker build \
156-
--build-arg PUID=1000 \
157-
--build-arg PGID=1000 \
158-
--build-arg USER=appuser \
159-
-t snowdreamtech/base:debian-custom \
160-
./docker/debian/
161-
```
162-
163-
Or at runtime (requires rebuilding the image):
39+
### Simple
16440

16541
```bash
166-
docker run -d \
167-
--name=base \
168-
-e PUID=1000 \
169-
-e PGID=1000 \
170-
-e USER=appuser \
171-
snowdreamtech/base:debian
172-
```
173-
174-
**Note**: User creation only occurs when `PUID≠0`, `PGID≠0`, and `USER≠root`.
175-
176-
## Docker Compose Examples
177-
178-
### Simple Configuration
179-
180-
```yaml
18142
services:
18243
base:
183-
image: snowdreamtech/base:debian
184-
container_name: base
44+
image: snowdreamtech/devcontainers:latest
45+
container_name: devcontainers
18546
environment:
18647
- TZ=Asia/Shanghai
18748
restart: unless-stopped
18849
```
18950

190-
### Advanced Configuration
51+
### Advance
19152

192-
```yaml
53+
```bash
19354
services:
19455
base:
195-
image: snowdreamtech/base:debian
196-
container_name: base
56+
image: snowdreamtech/devcontainers:latest
57+
container_name: devcontainers
19758
environment:
19859
- TZ=Asia/Shanghai
199-
- DEBUG=true
200-
- KEEPALIVE=1
20160
volumes:
202-
- /path/to/data:/data
61+
- /path/to/data:/path/to/data
20362
restart: unless-stopped
20463
```
20564

206-
## Semantic Versioning Tags
207-
208-
Images follow semantic versioning with the format: `{major}-v{major}.{minor}.{patch}`
209-
210-
Examples:
211-
212-
- `snowdreamtech/base:debian-13-v13.5.0`
213-
- `snowdreamtech/base:alpine-3-v3.24.0`
214-
- `snowdreamtech/base:rocky-10-v10.2.0`
215-
216-
This format allows:
217-
218-
- **Major version pinning**: `debian-13` (tracks latest 13.x.x)
219-
- **Full version pinning**: `debian-13-v13.5.0` (exact version)
220-
- **Latest tag**: `debian` or `latest` (tracks most recent release)
221-
222-
## Architecture Support
223-
224-
Each distribution variant supports multiple CPU architectures for deployment across diverse hardware platforms:
225-
226-
| Variant | Architectures |
227-
|---------|---------------|
228-
| **Debian** | i386, amd64, arm32v5, arm32v7, arm64, mips64le, ppc64le, s390x |
229-
| **Alpine** | i386, amd64, arm32v6, arm32v7, arm64, ppc64le, riscv64, s390x |
230-
| **Rocky** | i386, amd64, arm32v5, arm32v7, arm64, mips64le, ppc64le, s390x |
231-
232-
Docker automatically selects the appropriate architecture for your platform when pulling images.
233-
234-
## Entrypoint System
235-
236-
The base template includes a flexible entrypoint system that executes custom initialization scripts before starting your application.
237-
238-
### How It Works
239-
240-
1. The `docker-entrypoint.sh` script runs at container startup
241-
2. It executes all executable scripts in `/usr/local/bin/entrypoint.d/` in lexical order
242-
3. Each script receives the container's command-line arguments
243-
4. If any script fails, the container stops (fail-fast behavior)
244-
245-
### Adding Custom Initialization
246-
247-
Create custom initialization scripts in your derived Dockerfile:
248-
249-
```dockerfile
250-
FROM snowdreamtech/base:debian
251-
252-
# Add your custom initialization script
253-
COPY my-init.sh /usr/local/bin/entrypoint.d/20-my-init.sh
254-
RUN chmod +x /usr/local/bin/entrypoint.d/20-my-init.sh
255-
256-
# Your application setup
257-
COPY app /app
258-
CMD ["/app/start.sh"]
259-
```
260-
261-
### Debug Mode
262-
263-
Enable debug output to troubleshoot entrypoint execution:
264-
265-
```bash
266-
docker run -e DEBUG=true snowdreamtech/base:debian
267-
```
268-
269-
Output example:
270-
271-
```
272-
→ [ENTRYPOINT] Executing all scripts in /usr/local/bin/entrypoint.d
273-
→ Running /usr/local/bin/entrypoint.d/10-base-init.sh
274-
→ [ENTRYPOINT] Done.
275-
```
276-
277-
## Development
278-
279-
### Prerequisites
280-
281-
- Docker (>= 20.10)
282-
- Docker Buildx plugin
283-
284-
### Building Locally
285-
286-
```bash
287-
# Build all variants
288-
make build
289-
290-
# Build specific variant
291-
docker build -t base:debian ./docker/debian/
292-
docker build -t base:alpine ./docker/alpine/
293-
docker build -t base:rocky ./docker/rocky/
294-
```
295-
296-
### Testing
65+
# Development
29766

29867
```bash
299-
# Test default configuration
300-
docker run --rm base:debian id
301-
302-
# Test custom user creation
303-
docker build --build-arg PUID=1000 --build-arg PGID=1000 --build-arg USER=testuser -t base:debian-test ./docker/debian/
304-
docker run --rm base:debian-test id
305-
# Expected: uid=1000(testuser) gid=1000(testuser)
306-
307-
# Test DEBUG mode
308-
docker run --rm -e DEBUG=true base:debian
68+
docker buildx create --use --name build --node build --driver-opt network=host
69+
docker buildx build -t snowdreamtech/devcontainers --platform=linux/amd64,linux/arm64 . --push
30970
```
31071

31172
## Reference
31273

31374
1. [使用 buildx 构建多平台 Docker 镜像](https://icloudnative.io/posts/multiarch-docker-with-buildx/)
314-
2. [如何使用 docker buildx 构建跨平台 Go 镜像](https://waynerv.com/posts/building-multi-architecture-images-with-docker-buildx/#buildx-%E7%9A%84%E8%B7%A8%E5%B9%B3%E5%8F%B0%E6%9E%84%E5%BB%BA%E7%AD%96%E7%95%A5)
315-
3. [Building Multi-Arch Images for Arm and x86 with Docker Desktop](https://www.docker.com/blog/multi-arch-images/)
316-
4. [How to Rapidly Build Multi-Architecture Images with Buildx](https://www.docker.com/blog/how-to-rapidly-build-multi-architecture-images-with-buildx/)
317-
5. [Faster Multi-Platform Builds: Dockerfile Cross-Compilation Guide](https://www.docker.com/blog/faster-multi-platform-builds-dockerfile-cross-compilation-guide/)
318-
6. [docker/buildx](https://github.com/docker/buildx)
319-
320-
## Contact (备注：base)
321-
322-
* Email: <sn0wdr1am@qq.com>
323-
* QQ: 3217680847
324-
* QQ群: 949022145
325-
* WeChat/微信群: sn0wdr1am
75+
1. [如何使用 docker buildx 构建跨平台 Go 镜像](https://waynerv.com/posts/building-multi-architecture-images-with-docker-buildx/#buildx-%E7%9A%84%E8%B7%A8%E5%B9%B3%E5%8F%B0%E6%9E%84%E5%BB%BA%E7%AD%96%E7%95%A5)
76+
1. [Building Multi-Arch Images for Arm and x86 with Docker Desktop](https://www.docker.com/blog/multi-arch-images/)
77+
1. [How to Rapidly Build Multi-Architecture Images with Buildx](https://www.docker.com/blog/how-to-rapidly-build-multi-architecture-images-with-buildx/)
78+
1. [Faster Multi-Platform Builds: Dockerfile Cross-Compilation Guide](https://www.docker.com/blog/faster-multi-platform-builds-dockerfile-cross-compilation-guide/)
79+
1. [docker/buildx](https://github.com/docker/buildx)
80+
81+
## Contact (备注：devcontainers)
82+
83+
- Email: sn0wdr1am@qq.com
84+
- QQ: 3217680847
85+
- QQ群: 949022145
86+
- WeChat/微信群: sn0wdr1am
32687

32788
## License
32889

0 commit comments

Comments
 (0)