Image management
Chapter objectives
- Manage local images
- Pull from registries
- Build images
- Configure private registries
1 - List of images
Overview
┌─────────────────────────────────────────────────────────────────┐
│ 🖼️ Images [+ Build] [Pull Image] │
├─────────────────────────────────────────────────────────────────┤
│ □ Repository Tag ID Size │
│ ─────────────────────────── ───────────────────────────────────│
│ □ nginx alpine a8758716bb6a 40.7 MB │
│ □ nginx latest 3f8a4339aadd 187 MB │
│ □ postgres 15 3db8720ecbf5 412 MB │
│ □ redis 7-alpine 5685937b6bc1 32 MB │
│ □ myapp v1.0 abc123def456 250 MB │
│ □ <none> <none> xyz789... 150 MB │
│ │
│ Total: 6 images (1.1 GB) | Unused: 2 images (300 MB) │
│ │
└─────────────────────────────────────────────────────────────────┘
Displayed information
| Column | Description |
|---|---|
| Repository | Image name |
| Tag | Version |
| ID | Short identifier |
| Size | Size on disk |
| Created | Creation date |
| Used | Whether used by a container |
2 - Pull an image
Pull interface
┌─────────────────────────────────────────────────────────────────┐
│ Pull Image │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Registry: [Docker Hub ▼] │
│ │
│ Image: [nginx:alpine ] │
│ │
│ ☐ Always pull the latest version │
│ │
│ [Pull the image] │
│ │
└─────────────────────────────────────────────────────────────────┘
Supported formats
# Image officielle
nginx
# Avec tag
nginx:1.25-alpine
# Depuis Docker Hub
library/nginx:latest
# Depuis un registre privé
registry.example.com/myapp:v1
# Avec digest
nginx@sha256:abc123...
Download progress
┌─────────────────────────────────────────────────────────────────┐
│ Pulling nginx:alpine... │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ✅ Layer 1/5: Already exists │
│ ✅ Layer 2/5: Already exists │
│ ⏳ Layer 3/5: Downloading... 15.2 MB / 23.5 MB (65%) │
│ ⏳ Layer 4/5: Waiting... │
│ ⏳ Layer 5/5: Waiting... │
│ │
│ Progress: ████████████████░░░░░░░░░░░░░░ 65% │
│ │
└─────────────────────────────────────────────────────────────────┘
3 - Build an image
Build interface
┌─────────────────────────────────────────────────────────────────┐
│ Build Image │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Method: ( ) Web editor (•) Upload ( ) Git repository │
│ │
│ Name: [myapp ] │
│ Tag: [v1.0 ] │
│ │
│ Dockerfile: │
│ ┌────────────────── ───────────────────────────────────────┐ │
│ │ FROM node:18-alpine │ │
│ │ WORKDIR /app │ │
│ │ COPY package*.json ./ │ │
│ │ RUN npm ci --only=production │ │
│ │ COPY . . │ │
│ │ EXPOSE 3000 │ │
│ │ CMD ["node", "server.js"] │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ Additional files: [📁 Upload files...] │
│ │
│ [Build the image] │
│ │
└─────────────────────────────────────────────────────────────────┘
Build options
| Option | Description |
|---|---|
| Web editor | Write the Dockerfile directly |
| Upload | Upload a tar with the context |
| Git repository | Clone from Git |
| URL | Download from a URL |
Build from Git
┌─────────────────────────────────────────────────────────────────┐
│ Build from Git │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Repository URL: [https://github.com/user/repo ] │
│ │
│ Reference: [main ] │
│ │
│ Dockerfile path: [Dockerfile ] │
│ │
│ ☐ Use authentication │
│ │
│ Build args: │
│ [NODE_ENV ] = [production ] [+ Add] │
│ │
└─────────────────────────────────────────────────────────────────┘
4 - Actions on images
Actions menu
| Action | Description |
|---|---|
| Pull | Re-download (update) |
| Push | Push to a registry |
| Tag | Add a tag |
| Export | Export as tar |
| Remove | Remove |
Tag an image
┌─────────────────────────────────────────────────────────────────┐
│ Tag Image: nginx (abc123...) │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Registry: [registry.example.com ▼] │
│ │
│ Repository: [mycompany/nginx ] │
│ │
│ Tag: [v1.0 ] │
│ │
│ [Tag] │
│ │
└─────────────────────────────────────────────────────────────────┘
Push to a registry
┌─────────────────────────────────────────────────────────────────┐
│ Push Image │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Image: mycompany/nginx:v1.0 │
│ │
│ Registry: registry.example.com │
│ │
│ Pushing... │
│ ✅ Layer 1/4: Pushed │
│ ✅ Layer 2/4: Pushed │
│ ⏳ Layer 3/4: Pushing... 45% │
│ ⏳ Layer 4/4: Waiting │
│ │
└─────────────────────────────────────────────────────────────────┘
5 - Docker registries
Add a registry
Settings > Registries > + Add registry
┌─────────────────────────────────────────────────────────────────┐
│ Add Registry │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Type: (•) Custom registry │
│ ( ) Docker Hub │
│ ( ) AWS ECR │
│ ( ) Azure Container Registry │
│ ( ) GitLab │
│ ( ) GitHub │
│ ( ) Quay.io │
│ │
│ Name: [My Registry ] │
│ │
│ URL: [registry.example.com ] │
│ │
│ Authentication: │
│ Username: [admin ] │
│ Password: [•••••••••• ] │
│ │
│ [Add registry] │
│ │
└─────────────────────────────────────────────────────────────────┘
Supported registries
| Type | Configuration |
|---|---|
| Docker Hub | Username + Access Token |
| AWS ECR | Access Key + Secret + Region |
| Azure ACR | URL + Username + Password |
| GitLab | URL + Deploy Token |
| GitHub | ghcr.io + PAT |
| Custom | URL + credentials |
Use a registry
Once configured, the registry appears in:
- Pull image (registry selection)
- Push image (destination)
- Build (destination after build)
6 - Image cleanup
Dangling images (no tag)
┌─────────────────────────────────────────────────────────────────┐
│ 🖼️ Images │
├─────────────────────────────────────────────────────────────────┤
│ Show: [All ▼] [Dangling images only] │
│ │
│ □ <none> <none> abc123... 150 MB 2 weeks ago │
│ □ <none> <none> def456... 200 MB 3 weeks ago │
│ □ <none> <none> ghi789... 100 MB 1 month ago │
│ │
│ [Remove selected] [Remove all dangling images] │
│ │
└─────────────────────────────────────────────────────────────────┘
Unused images
┌─────────────────────────────────────────────────────────────────┐
│ Image Cleanup │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Unused images: 5 (1.2 GB) │
│ │
│ □ nginx:1.23 Not used by any container 187 MB │
│ □ postgres:14 Not used by any container 400 MB │
│ □ redis:6 Not used by any container 32 MB │
│ │
│ ⚠️ Removing unused images will free 1.2 GB │
│ │
│ [Prune unused images] │
│ │
└─────────────────────────────────────────────────────────────────┘
7 - Details of an image
Inspection
┌─────────────────────────────────────────────────────────────────┐
│ 🖼️ nginx:alpine │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Details: │
│ ─────────────────────────────────────────────────────────────│
│ ID: sha256:a8758716bb6aa... │
│ Created: 2024-01-10 00:00:00 │
│ Size: 40.7 MB │
│ Architecture: amd64 │
│ OS: linux │
│ │
│ Layers (5): │
│ ─────────────────────────────────────────────────────────────│
│ 1. ADD file:... (3.4 MB) │
│ 2. CMD ["/bin/sh"] │
│ 3. LABEL maintainer=... │
│ 4. RUN /bin/sh -c set -x... │
│ 5. COPY file:... │
│ │
│ Environment: │
│ ─────────────────────────────────────────────────────────────│
│ PATH=/usr/local/sbin:/usr/local/bin:... │
│ NGINX_VERSION=1.25.3 │
│ │
└─────────────────────────────────────────────────── ──────────────┘
8 - Best practices
Tag management
# ✅ Utiliser des versions spécifiques
nginx:1.25.3-alpine
# ⚠️ Éviter latest en production
nginx:latest
# ✅ Taguer vos images avec des versions
myapp:v1.2.3
myapp:v1.2.3-20240115
Regular cleanup
- Remove dangling images regularly
- Remove old unused versions
- Monitor disk space through the dashboard
Security
# ✅ Utiliser des registres authentifiés
# ✅ Scanner les images avant déploiement
# ✅ Éviter les images non officielles
# ✅ Garder les images à jour
Summary
| Action | How |
|---|---|
| List | Images section |
| Pull | Pull Image |
| Build | Build Image |
| Tag | Tag action |
| Push | Push action |
| Remove | Remove action |
| Prune | Remove dangling |
Key points
- Portainer supports all major registries
- Building supports Git, upload and web editor
- Dangling images consume space unnecessarily
- Configure your registries in Settings
Practical exercises
- Pull the
python:3.11-alpineimage - Build a simple image from the web editor
- Configure a Docker Hub registry
- Clean up unused images