DEV Community: Anatole HAGBE

Automatiser le déploiement de BMI et observer son fonctionnement : premiers pas avec le monitoring et les logs

Anatole HAGBE — Fri, 30 Oct 2026 11:17:20 +0000

Dans les articles précédents, j'ai installé un cluster K3s avec Ansible et y ai déployé BMI, une application de calcul de l'indice de masse corporelle (IMC), depuis mon pipeline GitLab. Une commande kubectl rollout status qui réussit me confirme que le déploiement a abouti et que les pods sont prêts. Mais elle ne me dit pas comment l'application se comporte ni pourquoi elle pourrait cesser de fonctionner. Une question s'impose alors : comment passer d'une application qui fonctionne à un service dont on peut observer le comportement et diagnostiquer les problèmes ?

Côté déploiement : peu de changements

Pour réduire les longues attentes, qui pouvaient atteindre plusieurs dizaines de minutes sur les runners gratuits, j'ai déployé mon propre runner GitLab dans mon cluster Kubernetes à l'aide du Helm chart officiel proposé par GitLab. Dans le projet BMI, j'ai créé un project runner et récupéré son token d'authentification. Voici un extrait de sa configuration :

runnerToken: "<GITLAB_TOKEN>"
concurrent: 2
logFormat: json
gitlabUrl: "https://gitlab.com"
rbac:
  create: true
  rules:
    - apiGroups: [""]
      resources:
        - configmaps
        - events
        - pods
        - pods/attach
        - pods/exec
        - secrets
        - services
      verbs: ["get", "list", "watch", "create", "patch", "update", "delete"]
serviceAccount:
  create: true
  name: gitlab-sa
runners:
  privileged: true
  config: |
    [[runners]]
      [runners.kubernetes]
        namespace = "{{.Release.Namespace}}"
        image = "alpine"
  tags: "bmi, kubernetes"
  name: "BMI-Runner"

J'ai ensuite exécuté la commande suivante pour installer le runner dans le namespace gitlab-runner :

helm install gitlab-runner \
  -f values.yml \
  -n gitlab-runner --create-namespace \
  oci://registry.gitlab.com/charts/charts.gitlab.io/release/gitlab-runner

Quelques secondes plus tard, le runner était opérationnel. J'ai enfin ajouté le tag bmi à mes jobs pour qu'ils puissent être exécutés sur ce runner.

Pourquoi cette pile d'outils ?

J'ai installé le Helm chart kube-prometheus-stack, qui regroupe Prometheus, Alertmanager, Grafana, Prometheus Operator, Node Exporter et kube-state-metrics.

Cette pile fournit de nombreux dashboards prêts à l'emploi ainsi que des règles d'alerte par défaut. Pour une première approche de l'observabilité, c'est un ensemble complet : je peux visualiser l'état de mon cluster en quelques minutes, sans avoir à assembler chaque composant avant d'obtenir mes premiers graphiques.

Pour collecter et stocker les logs, j'ai installé respectivement les charts Grafana Alloy et Grafana Loki.

Loki indexe principalement les labels associés aux logs, plutôt que leur contenu intégral. Cette approche permet de limiter les besoins en ressources de stockage et d'indexation, à condition de maîtriser la cardinalité des labels.

Alloy est l'agent de collecte et de traitement de Grafana. Il peut récupérer les logs des conteneurs, les traiter et les transmettre à Loki. Il prend également en charge la collecte de métriques et de traces. Il remplace Promtail, désormais en maintenance seulement.

J'ai publié dans mon dépôt GitLab les configurations utilisées ainsi que les procédures d'installation de ces différents charts.

Premiers pas avec le monitoring

Je m'intéresse à deux niveaux complémentaires : les ressources du cluster et le comportement de l'application.

Les ressources, avec la méthode USE.

USE signifie Utilization, Saturation, Errors. Cette méthode consiste à examiner l'utilisation, la saturation et les erreurs des ressources.

Les dashboards fournis par kube-prometheus-stack me permettent notamment de suivre l'utilisation du CPU et de la mémoire, les redémarrages des conteneurs et de nombreuses autres métriques du cluster.

Certaines métriques concernant mon application sont également disponibles, notamment celles liées aux ressources consommées par ses conteneurs. Je peux ainsi comparer la consommation réelle de BMI à mes estimations initiales.

Un premier constat, visible sur le graphique consacré au quota CPU, est que la consommation de l'application reste inférieure à mes prévisions.

Le service, avec la méthode RED.

RED signifie Rate, Errors, Duration. Contrairement à USE, cette méthode s'intéresse au comportement du service : combien de requêtes arrivent, combien échouent et combien de temps elles prennent.

J'ai instrumenté BMI pour exposer ses métriques sur l'endpoint /metrics :

le nombre de requêtes reçues ;
leur durée de traitement ;
la répartition des IMC calculés par catégorie, une métrique métier complémentaire qui ne relève pas directement de RED.

J'ai regroupé ces métriques dans un dashboard Grafana intitulé BMI Application Monitoring, accessible ici.

J'ai également configuré Alertmanager pour m'envoyer des notifications sur Discord dans trois situations :

le scraping des métriques de BMI échoue pendant cinq minutes consécutives ;
le taux d'erreurs HTTP 5xx dépasse 0,25 requête par seconde pendant cinq minutes ;
un pod redémarre plusieurs fois, quel que soit son namespace.

La capture ci-dessous montre une notification reçue sur Discord après que j'ai modifié le Deployment de BMI pour remplacer le nom de l'image Docker par un nom d'image et provoquer une imagePullBackOff. Mon application est down ce qui rend impossible la collection des métriques.

Cette expérience montre l'intérêt des alertes : elles permettent de détecter un problème sans avoir à surveiller constamment les dashboards.

Centraliser les logs

BMI écrit ses logs au format JSON à l'aide de slog. Alloy les collecte, puis Loki les stocke. Je peux ensuite les consulter dans Grafana.

La différence avec kubectl logs est concrète : je dispose d'une interface
centralisée pour rechercher et analyser les logs, en les mettant en regard des
autres données d'observabilité telles les métriques.

Difficultés et enseignements

Je n'ai pas rencontré de blocage majeur, mais la configuration de kube-prometheus-stack m'a demandé beaucoup de lecture pour comprendre le rôle des opérateurs dans Kubernetes. J'ai également consulté les documentations de Prometheus, d'Alertmanager et d'Alloy pour mieux comprendre leur fonctionnement et choisir les paramètres adaptés à mon environnement. Cette étape m'a surtout permis de comprendre comment les différents composants s'articulent : Prometheus collecte les métriques, Grafana les visualise, Alertmanager gère les alertes, Alloy collecte les logs et Loki les stocke.

Ce qu'il reste à améliorer

Aujourd'hui, BMI est déployée automatiquement dans l'environnement de staging. Ses métriques et ses logs sont consultables dans Grafana, et des alertes m'avertissent sur Discord en cas de problème. Il me reste à ajuster les demandes et limites de ressources, à configurer correctement les probes de disponibilité et de démarrage, à revoir les ServiceAccounts et leurs permissions, puis à préparer une version adaptée à un environnement de production.

Conclusion

Les Helm charts kube-prometheus-stack, Loki et Alloy m'ont permis de mettre rapidement en place une stack d'observabilité pour mon cluster Kubernetes. Je peux désormais suivre le comportement de BMI, détecter les anomalies et disposer des informations nécessaires pour en identifier les causes.

Pour aller plus loin, j'aimerais également installer et configurer chaque composant individuellement : Prometheus, Grafana, Alertmanager, Node Exporter, Prometheus Operator et kube-state-metrics. L'objectif n'est pas de réinventer l'existant ni de remplacer les Helm charts, mais de mieux comprendre le rôle de chaque brique, son fonctionnement et ses interactions avec les autres composants.

Une prochaine étape consistera à approfondir l'instrumentation de BMI et l'exposition de ses propres métriques. J'y consacrerai un article dédié.

Et vous, quelles métriques exposez-vous en priorité lorsque vous instrumentez une nouvelle application ?

Installer mon premier cluster K3s pour BMI : choix, automatisation et premières difficultés

Anatole HAGBE — Sun, 11 Oct 2026 21:18:35 +0000

Dans le premier article, j’ai présenté BMI et le plan de mon mentorat avec Edouard HINVI qui a généreusement mis à ma disposition un VPS qui tourne sous Ubuntu 26.04 LTS, avec environ 8 Go de RAM et 190 Go de disque.

Dans cet article, je fais le point de comment j’ai installé un cluster K3s avec Ansible, et y déployé BMI à l'aide de mon pipeline GitLab.

Pourquoi K3s

K3s est une distribution Kubernetes certifiée, légère, livrée en un seul binaire avec les composants de base déjà inclus. Je l’ai choisi, avec ses réglages par défaut, parce que mon workload est simple et léger, et que je voulais un cluster que mon VPS puisse porter sans difficulté. K3s simplifie l’installation. Plus tard, j’aimerais monter chaque composant (réseau, stockage, control plane, certificats, etc.) pour mieux comprendre le fonctionnement d’un cluster.

Pourquoi Ansible plutôt que Terraform

Le backlog prévoyait de créer le cluster avec Terraform et Cloud-init. Cependant, j'ai retenu Ansible pour l'installation. En effet le VPS existait déjà : il n’y avait rien à provisionner, seulement K3s à installer. De plus le projet K3s maintient une collection, k3s-ansible, qui automatise la création du cluster. Je n’ai qu’à décrire mon serveur et à lancer le playbook. Si j’avais dû créer le serveur, Terraform avec cloud-init aurait été le bon choix. Ce choix m'a poussé à modifier légèrement mon schéma d'architecture.

Installation

J'ai créé un nouveau projet Ansible en dehors de BMI pour installer le cluster et conserver les templates des manifests de déploiement. Il est géré avec uv, un gestionnaire de paquets et d’environnements Python rapide. Il isole les dépendances, facilite la gestion des versions et évite les conflits avec le système.

[project]
name = "bmi-cluster"
version = "0.1.0"
description = "Create BMI cluster and manage deployments"
requires-python = ">=3.14"
dependencies = [
    "ansible>=14.5.0",
    "ansible-lint>=26.9.0",
    "netaddr>=1.3.0",
]

Ensuite, j'ai créé un fichier requirements.yml qui référence la collection k3s-ansible.

collections:
  - name: https://github.com/k3s-io/k3s-ansible.git
    type: git
    version: 1.2.2

Son installation est très simple :

uv run ansible-galaxy install -r requirements.yml

Le fichier inventory.yml définit les paramètres de connexion SSH au VPS, qui sont lus dans les variables d’environnement.

k3s_cluster:
  vars:
    ansible_host: "{{ lookup('env', 'CLUSTER_HOST') }}"
    ansible_port: "{{ lookup('env', 'CLUSTER_PORT') }}"
    ansible_user: "{{ lookup('env', 'CLUSTER_USER') }}"
    api_endpoint: "{{ lookup('env', 'CLUSTER_HOST') }}"
    k3s_version: v1.37.0+k3s1
  children:
    server:
      hosts:
        staging:

La création du cluster tient en une commande :

uv run ansible-playbook -i inventory.yml k3s.orchestration.site

Les captures suivantes montrent le début et la fin de l'installation. Le warning sur la deuxième capture s'explique par le fait que j'ai un cluster mono-noeud : juste le server, pas d'agent.

À la fin de l'installation, j'ai vérifié le status du service systemd k3s, du noeud et des pods.

Le playbook k3s-ansible crée aussi sur le control node, un fichier ~/.kube/config.new qui donne un accès admin au cluster.

Déployer BMI depuis le pipeline

Côté BMI, j’ai modifié le pipeline pour déployer sur le cluster. Il récupère le fichier bmi.tpl.yml qui contient des templates de namespace, de deployment, de service et d' ingress. Il y injecte des paramètres pour générer un manifest Kubernetes, l’applique, vérifie le déploiement et sauvegarde le manifest dans les artifacts. Voici un extrait des templates :

# Namespace
apiVersion: v1
kind: Namespace
metadata:
  name: ${APP_NAMESPACE}
---

# Service
apiVersion: v1
kind: Service
metadata:
  name: bmi
  namespace: ${APP_NAMESPACE}
spec:
  selector:
    app: bmi
  ports:
    - port: 80
      targetPort: http

Le manifest complet est dans le dépôt.

Le déploiement se fait automatiquement dans l'environnement staging quand je pousse sur la branche main. Pour la production, il faut un tag et un clic manuel. Voici un extrait du pipeline de déploiement :

deploy-staging:
  extends: .deploy
  environment: staging
  rules:
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
    - when: never

deploy-production:
  extends: .deploy
  environment: production
  rules:
    - if: '$CI_COMMIT_TAG'
      when: manual
    - when: never

Le kubeconfig est stocké dans une variable GitLab secrète et masquée (KUBECONFIG_B64), encodée en base64. Il n’apparaît donc jamais dans les logs.

Difficultés

Ma principale difficulté a été de choisir les bonnes valeurs pour les ressources (cpu et memory) du Deployment, ainsi que les paramètres des probes (readinessProbe et livenessProbe). Pour l’instant, mes valeurs sont des estimations. Je vais les ajuster en observant la consommation réelle de BMI avec le monitoring, et en testant les probes sur le temps de démarrage de l’application.

Une autre est liée aux limites des runners du compte gratuit sur GitLab : mon pipeline reste parfois plus de 30 minutes en attente avant de démarrer. Je compte donc déployer mon propre runner dans le cluster Kubernetes et l'utiliser les prochaines fois.

Prochaines étapes

Rien n’a cassé, mais un cluster qui répond ne fait pas un service exploité. La semaine prochaine, je travaillerai sur le monitoring du cluster et de l’application, puis sur la centralisation des logs.

Je suis conscient que le kubeconfig actuellement donne un accès admin au cluster, ce qui est trop large pour un simple déploiement. Je vais créer un ServiceAccount limité au namespace de BMI, un par environnement. Et vous, comment sécurisez-vous l’accès de vos pipelines à votre cluster ?

De mon application Go à un service exploité sur Kubernetes : Point de départ et objectifs de mon mentorat

Anatole HAGBE — Sun, 04 Oct 2026 17:00:46 +0000

J'ai créé BMI, une application qui calcule l'indice de masse corporelle. Le sujet concerne beaucoup de monde, mais surtout, c'est un support que je maîtrise de bout en bout pour travailler ce qui m'intéresse vraiment : l'exploitation d'un service.

Les captures d'écran montrent l'état actuel de BMI. Un formulaire demande le nom, la taille et le poids. Une fois validé, un modal affiche l'IMC, la catégorie correspondante (normal, surpoids, etc.) et un court message, par exemple une invitation à revoir son alimentation. Aucune donnée n'est stockée, il n'y a pas d'authentification et aucun secret à gérer. Le code est en Go, avec la seule bibliothèque standard pour l'instant. Plus tard, j'imagine un compte utilisateur, un historique pour suivre son évolution et des notifications.

Côté DevOps, il y a déjà une base. Le code est sur GitLab, et un pipeline exécute les tests unitaires, construit l'image Docker, la scanne, puis la pousse sur Docker Hub. Un environnement de test tourne sur AWS et l'application expose un healthcheck. En revanche, il n'y a pas encore de supervision. C'est là que se situe la différence entre une application qui fonctionne et un service exploitable.

BMI n'a jamais été soumise à de vraies conditions de production. Je ne sais pas encore comment elle réagit quand un déploiement échoue, quand un pod redémarre ou quand il faut comprendre une panne à partir de ce qu'on observe plutôt que de ce qu'on suppose. Un healthcheck dit si le service répond, pas pourquoi il ne répond plus.

Pour travailler ces questions, je serai accompagné pendant quatre semaines (deux séances de deux heures par semaine) par Edouard HINVI, Senior Ingénieur DevOps et mentor chez Help All Skills qui organise cet accompagnement. Nous avons posé un backlog dès la première séance. Je joue à la fois le rôle de développeur et de DevOps, mais le mentorat cible uniquement le second.

Cette semaine, j’ai mis à jour la documentation de BMI en y ajoutant, entre autres, le schéma de l’architecture cloud. J’ai opté pour un cluster K3s mono-nœud, compte tenu de mon budget limité. J’ai enfin mis en place le pipeline qui construit l’image, la scanne, puis la pousse dans le registre Docker Hub.

La semaine prochaine, je créerai le cluster avec Terraform, y déploierai BMI et mettrai l’application en ligne en HTTPS.

Je passe mes journées à découvrir de nouveaux outils, à lire et à pratiquer, notamment en m’appuyant sur le blog de Stéphane ROBERT. Mais manipuler Kubernetes ne signifie pas encore savoir réellement l’exploiter. C’est précisément cet écart que je veux combler. C’est ambitieux pour quatre semaines, et je ne sais pas encore si tout tiendra dans le délai imparti. Les inconnues seront listées dès la première étape. Je publierai un article par semaine sur ce qui avance, mais aussi sur ce qui résiste.

Running Sonatype Nexus 3 on a 1 Gi RAM VPS — A Practical Guide

Anatole HAGBE — Sun, 05 Apr 2026 12:59:40 +0000

TL;DR — I self-host a private Docker registry and artifact store using Sonatype Nexus 3 on a VPS with only 1 Gi of RAM and 25 Gi of SSD. This post covers every decision made, every pitfall hit, and every config line tuned to make it work reliably in production.

Why Self-Host a Registry?

Every time I push an image to Docker Hub on a free plan, I think about rate limits, retention policies, and the slow creep of vendor lock-in. For personal and small team projects, a self-hosted registry gives you:

No rate limits on pulls (critical in CI/CD pipelines)
Private images without paying for a cloud registry
A single artifact store for Docker images, npm packages, Maven artifacts, and more — all under one roof
Full control over retention and access

The catch: Sonatype Nexus 3 is a Java application. It was built for enterprise servers, not budget VPS instances. The official documentation recommends a minimum of 8 Gi of RAM. Running it on 1 Gi is a constraint-driven engineering problem — and those are my favourite kind.

The Setup

Infrastructure

| Component     | Details                                                           |
| ------------- | ------------------------------------------------------------------|
| VPS           | 1 vCPU, 1 Gi RAM, 25 Gi SSD                                       |
| OS            | Ubuntu 22.04 LTS                                                  |
| Nexus version | 3.90.2-alpine                                                     |
| Database      | PostgreSQL (external, on the same host)                           |
| Reverse proxy | Traefik v3 with automatic TLS                                     |
| DNS           | `repository.bitnoises.com` (UI), `registry.bitnoises.com` (Docker)|

Architecture

Traefik handles all TLS termination. Nexus never sees raw HTTPS traffic — it only speaks plain HTTP internally, which simplifies configuration considerably.

The Memory Problem

Here is the honest picture of my RAM budget before Nexus even starts:

Total RAM:              957 Mi
OS + kernel:           ~150 Mi
Docker daemon:          ~50 Mi
Traefik:                ~30 Mi
PostgreSQL:             ~80 Mi
─────────────────────────────
Available for Nexus:   ~647 Mi

Nexus is a JVM application. Its memory footprint has two main components:

Heap (-Xmx) — object allocations, managed by the garbage collector
Direct memory (-XX:MaxDirectMemorySize) — off-heap buffers, used heavily for I/O

The default Sonatype recommendation is -Xmx2703m. On my VPS, that would require 4× the available RAM. The JVM would immediately start swapping and the container would be OOM-killed within minutes.

The solution is aggressive but careful downsizing.

JVM Tuning

-Xms128m                      # Start heap small, grow as needed
-Xmx384m                      # Hard heap ceiling
-XX:MaxDirectMemorySize=192m  # Off-heap buffer ceiling
-XX:+UseG1GC                  # Better GC under memory pressure
-XX:MaxGCPauseMillis=300      # GC pause target
-XX:G1HeapRegionSize=4m       # Smaller regions = less wasted space
-XX:+UseStringDeduplication   # G1 deduplicates identical strings (~5-10% heap savings)
-XX:SoftRefLRUPolicyMSPerMB=0 # Aggressively clear soft references under pressure

The key insight is separating -Xms from -Xmx. Starting at 128m means the JVM consumes minimal RAM on boot and only grows the heap as Nexus actually needs it. On a quiet personal registry, it rarely needs to grow much past 250–300m in practice.

Total JVM footprint: ~680m. Docker mem_limit is set to 700m, leaving a 20m buffer for JVM overhead variability.

The Swap Imperative

Never run a JVM application on a machine with no swap.

Swap on SSD is not a performance strategy — it is a safety net. Without it, the Linux OOM killer will terminate your container the instant it crosses the memory limit, with no warning and no graceful shutdown. Nexus does not handle abrupt kills well; you risk database corruption or a blob store in an inconsistent state.

fallocate -l 2G /swapfile
chmod 600 /swapfile
mkswap /swapfile
swapon /swapfile
echo '/swapfile none swap sw 0 0' >> /etc/fstab

# Only use swap as a last resort
echo 'vm.swappiness=10' >> /etc/sysctl.conf
sysctl -p

With vm.swappiness=10, Linux strongly prefers to keep data in RAM and only swills to the swapfile under real pressure. The SSD takes a minor hit, but your service survives spikes.

After adding swap, my memory picture looked like this:

$ free -h
               total   used    free    buff/cache  available
Mem:           957Mi   194Mi   91Mi    671Mi       594Mi
Swap:          2.0Gi   125Mi   1.9Gi

The buff/cache column (671Mi) looks alarming but is not — Linux uses free RAM as disk cache, and that cache is immediately evictable the moment Nexus needs it. The available column (594Mi) is the number that matters.

The compose.yml

services:
  nexus:
    image: sonatype/nexus3:3.90.2-alpine
    container_name: nexus
    restart: unless-stopped
    user: "200:200"
    environment:
      INSTALL4J_ADD_VM_PARAMS: >-
        -Xms128m
        -Xmx384m
        -XX:MaxDirectMemorySize=192m
        -XX:+UseG1GC
        -XX:MaxGCPauseMillis=300
        -XX:G1HeapRegionSize=4m
        -XX:+UseStringDeduplication
        -XX:SoftRefLRUPolicyMSPerMB=0
        -Djava.util.prefs.userRoot=/nexus-data/javaprefs
        -Dnexus.datastore.enabled=true
        -Dnexus-ssl-proxy=true
      NEXUS_DATASTORE_NEXUS_JDBCURL: jdbc:postgresql://${DB_HOST}:5432/${DB_NAME}
      NEXUS_DATASTORE_NEXUS_USERNAME: ${DB_USER}
      NEXUS_DATASTORE_NEXUS_PASSWORD: ${DB_PASSWORD}
    volumes:
      - "./data:/nexus-data"
    mem_limit: 700m
    memswap_limit: 1400m      # 700m RAM + 700m swap headroom
    healthcheck:
      test: ["CMD-SHELL", "curl -sf http://localhost:8081/service/rest/v1/status || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 180s      # Nexus is slow to boot on constrained hardware
    networks:
      - traefiknetwork
      - infra
    labels:
      - "traefik.enable=true"
      - "traefik.docker.network=traefiknetwork"
      # UI
      - "traefik.http.routers.nexus-ui.rule=Host(`${NEXUS_HOST}`)"
      - "traefik.http.routers.nexus-ui.entrypoints=websecure"
      - "traefik.http.routers.nexus-ui.tls=true"
      - "traefik.http.routers.nexus-ui.tls.certresolver=letsencrypt"
      - "traefik.http.routers.nexus-ui.service=nexus-ui"
      - "traefik.http.services.nexus-ui.loadbalancer.server.port=8081"
      # Docker registry
      - "traefik.http.routers.nexus-docker.rule=Host(`${REGISTRY_HOST}`)"
      - "traefik.http.routers.nexus-docker.entrypoints=websecure"
      - "traefik.http.routers.nexus-docker.tls=true"
      - "traefik.http.routers.nexus-docker.tls.certresolver=letsencrypt"
      - "traefik.http.routers.nexus-docker.service=nexus-docker"
      - "traefik.http.services.nexus-docker.loadbalancer.server.port=5000"
      - "traefik.http.middlewares.docker-headers.headers.customrequestheaders.Docker-Distribution-Api-Version=registry/2.0"
      - "traefik.http.middlewares.nexus-docker-buffering.buffering.maxRequestBodyBytes=0"
      - "traefik.http.routers.nexus-docker.middlewares=docker-headers,nexus-docker-buffering"

networks:
  traefiknetwork:
    external: true
  infra:
    external: true

Things worth calling out

user: "200:200" — The Nexus image internally runs as UID 200. Explicitly setting this prevents accidental root execution. The ./data directory must be pre-owned: sudo chown -R 200:200 ./data.

start_period: 180s — Without this, Docker marks the container unhealthy before it has finished booting, which can trigger restart loops. On constrained hardware, Nexus takes 2–3 minutes to start.

maxRequestBodyBytes=0 — The single most important Traefik label for a Docker registry. Without it, pushing any image layer larger than Traefik's default body size limit (2m) will fail with a cryptic 413 error.

-Dnexus-ssl-proxy=true — Tells Nexus it is behind a TLS-terminating proxy. Without this, the UI generates incorrect http:// URLs in some contexts.

PostgreSQL vs Embedded Database

Nexus 3 supports two database backends: an embedded H2 database and external PostgreSQL. I chose PostgreSQL for several reasons:

Reliability — H2 is fine for development, but I've seen it corrupt under abrupt JVM kills. PostgreSQL handles dirty shutdowns gracefully.
Observability — I can query the database directly to inspect state, run backups, and monitor connection counts.
Consistency — PostgreSQL is already running on my infrastructure for other services. One less moving part.

The tradeoff: there is no admin.password file on a PostgreSQL-backed install. The default credentials are simply admin / admin123, and Nexus forces a password change on first login.

Configuring the Docker Registry

After the first login:

Enable the Bearer Token Realm

Administration → Security → Realms → move Docker Bearer Token Realm to Active.

This is the single most common cause of 401 Unauthorized errors when using docker login. It must be enabled.

Create the Repository

Administration → Repository → Repositories → Create repository → docker (hosted)

Set the HTTP port to 5000 (this is what Traefik will route to), leave HTTPS unchecked (Traefik handles that), and set the deployment policy to your preference.

CI/CD Integration

I created a dedicated ci user with a minimal role, following the principle of least privilege. The role has only the privileges needed to push and pull from the Docker repository — no admin access, no access to other repositories.

In GitLab CI/CD:

stages:
  - push

push-alpine-to-nexus:
  stage: push
  image: docker:29.2.1
  services:
    - docker:29.2.1-dind

  variables:
    DOCKER_TLS_CERTDIR: ""

  script:
    # Log in to the private registry
    - echo "$NEXUS_PASSWORD" | docker login registry.bitnoises.com \
        --username "$NEXUS_USER" \
        --password-stdin

    # Pull Alpine image from Docker Hub
    - docker pull alpine:latest

    # Tag the image for the private registry
    - docker tag alpine:latest registry.bitnoises.com/alpine:latest

    # Push the image to Nexus
    - docker push registry.bitnoises.com/alpine:latest

Using the commit SHA as the image tag instead of latest gives you full traceability — every deployment can be traced back to an exact commit.

Disk Management

The SSD is the other constraint. 25 Gi sounds like a lot until you start storing Docker images — a typical Node.js app image is 200–400 Mi, and you accumulate many versions fast.

Cleanup Policies

In Administration → Repository → Cleanup Policies, I created a policy that removes:

Components older than 30 days
Components not downloaded in 14 days

Attached to the docker-hosted repository and scheduled as a weekly task, this keeps the blob store from growing unbounded.

Monitoring

# How much is Nexus actually using?
du -sh ./data/blobs/

# Docker layer cache on the host
docker system df

# Full picture
df -h

Lessons Learned

JVM memory is not just heap. Many guides say "set -Xmx to half your RAM" without mentioning direct memory, metaspace, code cache, or JVM thread stacks. The real footprint is heap + direct + ~100m of JVM internals. Budget for all of it.

Swap before anything else. I almost deployed without swap because "SSD swap is slow." SSD swap at 10% swappiness is effectively never used during normal operation, but it has saved me from OOM kills more than once during Nexus startup when memory pressure is highest.

Traefik label order matters. The middlewares label must reference middleware names defined in other labels in the same service. If you define docker-headers and nexus-docker-buffering but only reference one in the router label, the other silently does nothing.

start_period is not optional for slow services. Docker's healthcheck start_period is the grace period before failed checks count against retries. For a service that takes 2–3 minutes to boot, setting this to 30s means Docker will restart the container before it has even finished starting — creating an infinite restart loop that looks like a memory issue.

PostgreSQL default credentials are not in the logs. Coming from H2-backed Nexus where an admin.password file is generated, this caught me off guard. The PostgreSQL-backed install simply uses admin / admin123 with no file or log entry indicating this.

The Result

A fully functional private Docker registry and artifact store, running reliably on hardware that costs a few euros a month. Memory usage in steady state:

$ docker stats nexus --no-stream
CONTAINER   CPU %   MEM USAGE / LIMIT   MEM %
nexus       0.3%    412MiB / 700MiB     58.9%

58% memory utilisation at idle, with 42% headroom before the hard limit and 700m of swap available beyond that. For a personal infrastructure project, that is a comfortable margin.

The full configuration, scripts, and documentation are available on GitHub: gitlab.com/hanatole/nexus

Have questions or improvements? Open an issue on the repository.