Pourquoi self-héberger une API Go sur un VPS
Contrairement à Java ou Node, une application Go (avec le framework Gin) se compile en un binaire statique unique qui n'a besoin ni d'interpréteur, ni de runtime, ni de bibliothèque partagée. Vous pouvez littéralement déposer le binaire sur un VPS et l'exécuter. Cette légèreté change tout pour le self-hosting : une API Gin tourne dans 15 à 30 Mo de RAM et démarre en quelques millisecondes. Sur un VPS, vous exploitez à fond cette efficacité : un serveur d'entrée de gamme suffit à servir une charge que les langages interprétés exigeraient sur une machine bien plus grosse. Vous évitez aussi la complexité des images Docker volumineuses : une image scratch de 10 Mo suffit, et les builds comme les pulls sont quasi instantanés.
Bénéfices concrets
- Binaire statique unique : aucun runtime à installer, déploiement par simple copie de fichier
- Empreinte mémoire minuscule (15-30 Mo) permettant de saturer un petit VPS de requêtes
- Image Docker
scratchoudistrolessde 10-15 Mo : builds et pulls quasi instantanés - Démarrage en millisecondes : redéploiements et redémarrages sans interruption perceptible
- Concurrence native via les goroutines : un seul vCPU gère des milliers de connexions simultanées
- Surface d'attaque réduite : pas d'interpréteur ni de packages système à patcher
Prérequis matériels et logiciels
C'est là que Go brille : une API Gin sans base de données tient sur un VPS de 1 vCPU et 1 Go de RAM, et reste à l'aise. Avec PostgreSQL co-localisé, visez 2 Go pour être confortable. Vous n'avez même pas besoin de Go sur le serveur si vous compilez en CI ou en cross-compilation locale (GOOS=linux GOARCH=amd64 go build). Installez Docker et Docker Compose sur le VPS. Pointez un domaine api.mondomaine.com vers l'IP du VPS via un enregistrement A. 5 Go de disque suffisent largement. Sur votre poste de développement, Go 1.27+ est recommandé — téléchargez depuis go.dev/dl.
Dockerfile multi-stage avec image scratch
Le Dockerfile multi-stage est la clé d'une image finale minimale. La première étape compile le binaire dans un conteneur Go complet ; la seconde le copie dans une image scratch vide — aucun shell, aucun OS, juste votre binaire et les certificats CA pour les appels HTTPS sortants. Voici un Dockerfile complet pour un projet Gin :
FROM golang:1.27-alpine AS build
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -ldflags="-s -w" -o server .
FROM scratch
COPY --from=build /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
COPY --from=build /app/server /server
EXPOSE 8080
ENTRYPOINT ["/server"]Le flag CGO_ENABLED=0 force un binaire 100 % statique, indispensable pour que FROM scratch fonctionne. Les flags -ldflags="-s -w" suppriment les tables de debug et réduisent la taille du binaire d'environ 30 %. Le COPY des certificats CA est indispensable dès que votre API contacte des services externes en HTTPS (Stripe, SendGrid, etc.). Si vous avez besoin d'un shell pour déboguer, remplacez FROM scratch par FROM gcr.io/distroless/static-debian12 — même légèreté, mais avec quelques outils de base.
Docker Compose de production avec Nginx et Certbot
Créer la structure de fichiers sur le VPS
Connectez-vous en SSH et créez le dossier du projet :
mkdir -p /opt/myapp/{nginx/conf.d,certbot/www,certbot/conf} && cd /opt/myapp. Cette structure accueillera la configuration Nginx et les volumes Certbot.Écrire le fichier docker-compose.yml
Créez
/opt/myapp/docker-compose.ymlavec trois services :app(votre image Go),nginx(reverse proxy) etcertbot(renouvellement SSL). Exemple minimal :services: app: image: monapp:latest restart: unless-stopped env_file: .env expose: - "8080" nginx: image: nginx:1.27-alpine restart: unless-stopped ports: - "80:80" - "443:443" volumes: - ./nginx/conf.d:/etc/nginx/conf.d:ro - ./certbot/www:/var/www/certbot:ro - ./certbot/conf:/etc/letsencrypt:ro depends_on: - app certbot: image: certbot/certbot volumes: - ./certbot/www:/var/www/certbot - ./certbot/conf:/etc/letsencryptConfigurer Nginx en frontal
Créez
nginx/conf.d/app.conf. Commencez par un bloc HTTP seul pour valider le challenge ACME, puis ajoutez le bloc HTTPS après l'obtention du certificat :server { listen 80; server_name api.mondomaine.com; location /.well-known/acme-challenge/ { root /var/www/certbot; } location / { return 301 https://$host$request_uri; } } server { listen 443 ssl; server_name api.mondomaine.com; ssl_certificate /etc/letsencrypt/live/api.mondomaine.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/api.mondomaine.com/privkey.pem; location / { proxy_pass http://app:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } }Obtenir le certificat Let's Encrypt
Démarrez Nginx seul d'abord, puis lancez Certbot en mode standalone webroot :
docker compose up -d nginx && docker compose run --rm certbot certonly --webroot -w /var/www/certbot -d api.mondomaine.com --email [email protected] --agree-tos. Une fois le certificat émis, relancez Nginx :docker compose restart nginx.Builder et démarrer l'application
Buildez l'image Go sur le VPS (ou transférez-la via
docker save/loadou un registry privé) :docker build -t monapp:latest .. Puis démarrez la stack complète :docker compose up -d. Vérifiez les logs avecdocker compose logs -f app.Automatiser le renouvellement SSL
Ajoutez une crontab sur le VPS pour renouveler automatiquement le certificat chaque semaine :
(crontab -l 2>/dev/null; echo "0 3 * * 0 cd /opt/myapp && docker compose run --rm certbot renew && docker compose restart nginx") | crontab -. Certbot ne renouvelle effectivement que si l'expiration est dans moins de 30 jours.Configurer Gin pour la production
Dans votre code, passez Gin en mode release avec
gin.SetMode(gin.ReleaseMode)ou la variable d'environnementGIN_MODE=releasepour désactiver les logs verbeux de debug. Lisez le port et les secrets depuis l'environnement (os.Getenv), jamais en dur dans le code.
Live reload en développement avec air
En développement, recompiler et relancer manuellement à chaque modification est pénible. air (github.com/air-verse/air, actuellement v1.67.4) surveille votre arborescence et relance le binaire à chaque changement de fichier .go. Installation : go install github.com/air-verse/air@latest. Lancez simplement air à la racine de votre projet — un fichier .air.toml par défaut est généré automatiquement au premier lancement. Pour personnaliser les répertoires surveillés ou exclure vendor/ :
[build]
cmd = "go build -o ./tmp/server ."
bin = "./tmp/server"
include_ext = ["go", "html", "tmpl"]
exclude_dir = ["vendor", "testdata"]air ne convient qu'au développement local : n'installez jamais air dans votre image Docker de production.
Variables d'environnement et secrets
Ne codez jamais en dur les secrets (clés API, mots de passe de base de données, tokens JWT) dans le code source. La pratique standard en Go est de les lire depuis l'environnement avec os.Getenv("DB_PASSWORD"). Pour le développement local, un fichier .env chargé par godotenv simplifie le flux : go get github.com/joho/godotenv, puis au démarrage :
import "github.com/joho/godotenv"
func main() {
_ = godotenv.Load() // charge .env si présent, silencieux en prod
db := os.Getenv("DB_DSN")
port := os.Getenv("PORT")
if port == "" { port = "8080" }
// ...
}En production, passez les variables via le fichier env_file: .env de Docker Compose (ce fichier ne doit jamais être commité — ajoutez .env à votre .gitignore). Pour les secrets très sensibles (tokens, clés privées), préférez les secrets Docker ou un vault externe (Vault by HashiCorp, Infisical). La règle d'or : un secret dans un git log est un secret compromis.
Activez le profiling pprof de Go derrière un endpoint protégé : import _ "net/http/pprof" exposé sur un port interne uniquement accessible en SSH tunnel (ssh -L 6060:localhost:6060 user@vps). Vous obtenez des flame graphs CPU et mémoire en production réelle sans surcharge notable. Pensez aussi à compiler avec -ldflags="-s -w" pour réduire la taille du binaire de ~30 % en supprimant les tables de debug.
Dépannage : erreurs courantes
Voici les cinq erreurs les plus fréquentes lors d'un premier déploiement Go sur VPS, avec leurs messages exacts et la correction à appliquer.
1. standard_init_linux.go:228: exec user process caused: no such file or directory — Le binaire a été compilé avec CGO activé et l'image scratch ne contient aucune libc. Correction : recompilez avec CGO_ENABLED=0 go build -o server ..
2. exec format error — Le binaire a été compilé pour une architecture différente (ex. : macOS ARM → Linux AMD64). Correction : vérifiez GOOS=linux GOARCH=amd64 avant le build, ou buildez directement sur le VPS.
3. bind: address already in use (port 8080) — Un autre processus écoute déjà sur ce port. Vérifiez avec ss -tlnp | grep 8080 et arrêtez le processus conflictuel, ou changez le port dans votre .env.
4. x509: certificate signed by unknown authority ou certificate has expired — Votre conteneur scratch ne dispose pas des certificats CA (/etc/ssl/certs/ca-certificates.crt), ou le certificat Let's Encrypt a expiré. Correction : vérifiez que le COPY --from=build /etc/ssl/certs/ca-certificates.crt est présent dans votre Dockerfile, et relancez Certbot pour renouveler.
5. permission denied au démarrage du binaire — Le binaire n'est pas exécutable. Correction : vérifiez les permissions avec ls -la server et appliquez chmod +x server si nécessaire. Dans un Dockerfile, le COPY --from=build préserve normalement les permissions, mais un RUN chmod +x /server explicite garantit le résultat.
Déployer Go (Gin) en un clic depuis le Marketplace ServOrbit
Le Marketplace ServOrbit propose un template Go (Gin) Stack préconfiguré : Go depuis le binaire officiel go.dev, Nginx et PostgreSQL 16 sont installés automatiquement sur votre VPS dès la commande. Pas de session SSH pour l'installation de base — vous arrivez directement à l'étape de compiler votre projet et d'uploader le binaire. La fiche marketplace contient les spécifications exactes, les cas d'usage et un guide de première connexion.
Pour aller plus loin
Vous maîtrisez maintenant le déploiement d'une API Go sur VPS. Pour aller encore plus loin : configurez Traefik v3 comme reverse proxy à la place de Nginx — il gère le routage, les certificats Let's Encrypt et le load balancing dans un seul conteneur, avec une configuration déclarative en labels Docker (voir notre guide [Traefik v3 sur VPS](/blog/traefik-v3-vps-reverse-proxy)). Pour les mises à jour en production sans interruption, consultez notre article sur les [bonnes pratiques Docker Compose](/blog/docker-compose-mise-a-jour-best-practices-vps) : déploiements rolling, health checks et stratégies de rollback. Enfin, si vous préférez déléguer l'infrastructure, notre [template Go (Gin) dans le Marketplace](/marketplace/developpement/golang) provisionnne l'ensemble de la stack en quelques minutes.
