Mis apuntes · Aprende Go desde PHP

Se guardan solos en este navegador mientras escribes. Puedes usar Markdown. Al descargarlos, la primera línea es tu enlace personal al curso.

Lección 36 de 36 · Proyecto final: CRUD de tareas con SQLite ✦ WebMCP implementado

Fase 6: tests, apagado limpio y despliegue

10 min de lectura 3 retos

La última fase: dejar la app lista para vivir en un servidor. Repasas los tests de todas las capas, haces que el programa se apague sin cortar a nadie, lo metes en una imagen de Docker diminuta y lo pones detrás de Caddy o nginx.

¿De dónde vienen los nombres?

SIGINT = SIGnal INTerrupt (señal de interrupción)
La que manda el sistema cuando pulsas Ctrl+C en la terminal.
SIGTERM = SIGnal TERMinate (señal de terminar)
La forma educada de pedir a un programa que se cierre. Es la que envían docker stop, systemctl stop o Kubernetes. Si no hace caso, después llega SIGKILL, que no se puede ignorar.
CGO_ENABLED=0 = cgo (C + Go) enabled (activado) = 0
Compila sin nada de C: el binario no depende de ninguna librería del sistema y funciona en una imagen vacía.
distroless = distro (distribución de Linux) + less (sin)
Imágenes de Docker de Google que no traen ni shell ni gestor de paquetes: solo lo mínimo para ejecutar tu binario.
En 4 ideas
1/4

Cada capa se prueba a su manera: el dominio solo, los casos de uso con el repositorio en memoria, el repositorio con SQLite :memory: y la web con httptest. go test ./... lo lanza todo, como vendor/bin/phpunit.

1 · Los tests del proyecto, capa a capa

Has escrito tests en cada fase. Juntos forman una red de seguridad, como las redes de un trapecista: cada una a una altura distinta.

CapaCómo se pruebaVelocidadEn PHP
dominioTest de tabla, sin nada de fuera (fase 2)InstantáneoTest unitario de PHPUnit
casosdeusoCon repositorio.NuevoMemoria() o un repositorio falso (fase 4)InstantáneoCon un repositorio en memoria o createMock()
repositorioCon SQLite :memory: y las migraciones de verdad (fase 1)MilisegundosTest de integración con SQLite en memoria
webCon httptest y la app entera en memoria (fase 5)Milisegundos$this->get() de Laravel o WebTestCase de Symfony
$ go test ./...
?       tareas/cmd/tareas               [no test files]
ok      tareas/internal/casosdeuso      0.013s
ok      tareas/internal/dominio         0.013s
ok      tareas/internal/repositorio     0.020s
ok      tareas/internal/web             0.014s
$ go vet ./...
$

go vet no dice nada cuando todo está bien. main.go no tiene tests porque solo cablea piezas que ya están probadas. Mantenlo corto y así no hace falta.

2 · Apagado limpio: signal.NotifyContext y Shutdown

Imagina que cierras una tienda. Lo bruto es apagar la luz con clientes dentro. Lo correcto es cerrar la puerta (no entra nadie más), dejar que los de dentro paguen y, entonces sí, apagar. Si alguien tarda demasiado, le avisas y cierras igual.

Eso es un apagado limpio. Cuando haces docker stop, Docker manda SIGTERM, espera 10 segundos y, si el programa sigue vivo, lo mata con SIGKILL. Un programa que no escucha la señal muere a mitad de un INSERT.

PHP 8.5worker.php
<?php
declare(strict_types=1);

// Un proceso PHP que vive mucho (como un queue:work de Laravel).
// Con php-fpm no hace falta: el propio php-fpm gestiona las señales.
$rutaBd = getenv("RUTA_BD") ?: "tareas.db";
$seguir = true;

pcntl_async_signals(true);
foreach ([SIGINT, SIGTERM] as $senal) {
    pcntl_signal($senal, function () use (&$seguir): void {
        $seguir = false;
    });
}

echo "trabajando con {$rutaBd}" . PHP_EOL;
while ($seguir) {
    // Atender el siguiente trabajo...
    sleep(1);
}
echo "apagando..." . PHP_EOL;
Gomain.go
// cmd/tareas/main.go (el trozo del servidor)
func ejecutar() error {
    // ... abrir la BD, migrar y cablear (fases 1 a 5) ...
    srv := &http.Server{
        Addr:              ":" + puerto,
        Handler:           ctrl.Rutas(),
        ReadHeaderTimeout: 5 * time.Second,
    }

    // ctx se cancela con Ctrl+C (SIGINT) o con docker stop (SIGTERM).
    ctx, parar := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
    defer parar()

    // El servidor, en su propia goroutine (módulo 08).
    errServidor := make(chan error, 1)
    go func() {
        log.Printf("escuchando en http://localhost%s", srv.Addr)
        errServidor <- srv.ListenAndServe()
    }()

    // Esperar: o el servidor falla al arrancar, o llega la señal.
    select {
    case err := <-errServidor:
        return err
    case <-ctx.Done():
    }

    log.Println("apagando...")
    // Un ctx NUEVO con margen: el de la señal ya está cancelado.
    ctxApagado, cancelar := context.WithTimeout(context.Background(), 10*time.Second)
    defer cancelar()
    if err := srv.Shutdown(ctxApagado); err != nil {
        return err
    }
    log.Println("adiós")
    return nil
}

srv.Shutdown hace justo lo de la tienda: deja de aceptar conexiones, espera a que acaben las peticiones en curso y vuelve. Si se agota el plazo del ctx, devuelve un error y sales igual. Así se ve en la terminal al pulsar Ctrl+C:

$ go run ./cmd/tareas
2026/11/17 19:39:54 escuchando en http://localhost:8080
^C2026/11/17 19:39:57 apagando...
2026/11/17 19:39:57 adiós

¿Por qué? · En PHP no existe

¿Por qué tengo que programar yo el apagado? En PHP nunca lo hice

En PHP cada petición es un proceso corto que gestiona php-fpm. Cuando reinicias, php-fpm ya sabe esperar a que terminen los scripts en marcha (process_control_timeout). Tú nunca ves la señal.

En Go tu binario es el servidor (módulo 01): no hay nadie por encima que haga ese trabajo. Si no escuchas SIGTERM, cada despliegue corta las peticiones a medias y el usuario ve un error. Por eso existen signal.NotifyContext (la señal llega como un ctx cancelado, módulo 08) y srv.Shutdown.

Y un detalle traicionero: a Shutdown no le pases el ctx de la señal. Ese ya está cancelado, así que Shutdown no esperaría nada y cortaría a todos. Crea uno nuevo con context.WithTimeout(context.Background(), …).

El playground no puede recibir señales, pero la idea se ve con una simulación: tres peticiones en curso, una señal y un margen de 2 segundos:

Gomain.go
package main

import (
    "context"
    "fmt"
    "sync"
    "time"
)

func main() {
    // ctx hace de signal.NotifyContext: se cancela al llegar la señal.
    ctx, recibirSenal := context.WithCancel(context.Background())
    var enCurso sync.WaitGroup

    // Tres peticiones que tardan 1, 2 y 3 segundos.
    for i := 1; i <= 3; i++ {
        enCurso.Add(1)
        go func() {
            defer enCurso.Done()
            time.Sleep(time.Duration(i) * time.Second)
            fmt.Printf("petición %d terminada\n", i)
        }()
    }

    // El docker stop llega a los 500 ms.
    time.AfterFunc(500*time.Millisecond, recibirSenal)
    <-ctx.Done()
    fmt.Println("señal recibida: ya no entran peticiones nuevas")

    // Lo que hace Shutdown: esperar a las que están a medias, con un margen.
    terminadas := make(chan struct{})
    go func() {
        enCurso.Wait()
        close(terminadas)
    }()
    select {
    case <-terminadas:
        fmt.Println("apagado limpio")
    case <-time.After(2 * time.Second):
        fmt.Println("se acabó el margen: se corta la que falta")
    }
}

3 · Configuración por variables de entorno

El mismo binario corre en tu portátil y en el servidor. Lo que cambia (el puerto, la ruta de la base de datos) se lee de variables de entorno, como el .env de Laravel. En main.go hay una ayuda pequeña:

Gomain.go
// entorno lee una variable de entorno o devuelve el valor por defecto.
// En PHP: getenv("PUERTO") ?: "8080"
func entorno(clave, porDefecto string) string {
    if v := os.Getenv(clave); v != "" {
        return v
    }
    return porDefecto
}

Para poder probarla sin tocar el entorno real, se le puede pasar la función que lee las variables. En el programa le das os.Getenv y en los tests un map (funciones como valores, módulo 06):

Gomain.go
package main

import "fmt"

type Config struct {
    Puerto string
    RutaBD string
}

func entorno(getenv func(string) string, clave, porDefecto string) string {
    if v := getenv(clave); v != "" {
        return v
    }
    return porDefecto
}

func ConfigDesdeEntorno(getenv func(string) string) Config {
    return Config{
        Puerto: entorno(getenv, "PUERTO", "8080"),
        RutaBD: entorno(getenv, "RUTA_BD", "tareas.db"),
    }
}

func main() {
    local := map[string]string{}
    docker := map[string]string{"PUERTO": "9000", "RUTA_BD": "/datos/tareas.db"}
    for _, env := range []map[string]string{local, docker} {
        // En el programa real: ConfigDesdeEntorno(os.Getenv)
        getenv := func(clave string) string { return env[clave] }
        fmt.Printf("%+v\n", ConfigDesdeEntorno(getenv))
    }
}

4 · Un Dockerfile multi-stage

Para compilar hace falta Go entero; para ejecutar, solo el binario. Un Dockerfile multi-stage (de varias etapas) usa dos imágenes: una cocina grande para preparar el plato y un plato pequeño para servirlo. A producción solo viaja el plato.

$ cat Dockerfile
# --- Etapa 1: compilar (imagen grande, con Go) ---
FROM golang:1.26 AS build
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o /tareas ./cmd/tareas && mkdir /datos

# --- Etapa 2: ejecutar (imagen mínima, solo el binario) ---
FROM gcr.io/distroless/static-debian12:nonroot
COPY --from=build /tareas /tareas
COPY --from=build --chown=65532:65532 /datos /datos
ENV RUTA_BD=/datos/tareas.db PUERTO=8080
EXPOSE 8080
VOLUME /datos
ENTRYPOINT ["/tareas"]
  1. COPY go.mod go.sum + go mod download antes del resto: si solo cambias código, Docker reutiliza la capa de dependencias. Es el truco de copiar composer.json antes que src/.
  2. CGO_ENABLED=0 funciona gracias a modernc.org/sqlite (fase 1). Con un driver con cgo, la imagen final necesitaría las librerías de C.
  3. -trimpath quita las rutas de tu máquina del binario; -ldflags="-s -w" le quita la información de depuración y lo hace más pequeño.
  4. La imagen distroless :nonroot ejecuta como el usuario 65532, no como root. Por eso /datos, donde vive tareas.db, se copia con ese dueño.
  5. VOLUME /datos: la base de datos vive fuera de la imagen, en un volumen. Si no, se perdería en cada despliegue.
$ docker build -t tareas .
$ docker run -d --name tareas -p 127.0.0.1:8080:8080 -v tareas-datos:/datos tareas
$ curl -s localhost:8080/api/tareas
[]
$ docker stop tareas

¿Por qué? · En PHP no existe

¿Por qué una imagen sin sistema operativo? En PHP la imagen lleva de todo

Una imagen de PHP necesita el intérprete, php-fpm, las extensiones (pdo_sqlite, intl…) y normalmente nginx. Todo eso hay que instalarlo, ocupa espacio y hay que actualizarlo cuando sale un fallo de seguridad.

Un binario de Go compilado con CGO_ENABLED=0 no necesita nada: ni intérprete, ni librerías. La etapa de compilación ocupa cientos de megas; la imagen final de este proyecto, unos 14 MB. Y como no hay shell, si alguien encuentra un fallo en tu app no tiene un bash con el que seguir: hay mucho menos que atacar.

5 · El binario detrás de Caddy o nginx

Tu binario habla HTTP, pero en producción se le pone delante un proxy inverso: el portero del edificio. Recibe las visitas en el puerto 443 con HTTPS, mira el dominio y las pasa a tu app en 127.0.0.1:8080. Tu app no tiene que saber nada de certificados.

Con Caddy, que también está escrito en Go y pide el certificado de Let's Encrypt solo, bastan tres líneas:

$ cat /etc/caddy/Caddyfile
tareas.example.com {
    reverse_proxy 127.0.0.1:8080
}

Con nginx, el que ya usas con PHP, cambias el fastcgi_pass hacia php-fpm por un proxy_pass hacia tu binario:

server {
    listen 443 ssl;
    server_name tareas.example.com;
    # ssl_certificate y ssl_certificate_key: los de Let's Encrypt

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
PiezaPHPGo
Recibe la visita y el HTTPSnginx o ApacheCaddy o nginx (el mismo papel)
Ejecuta tu códigophp-fpm, un proceso por peticiónTu binario, una goroutine por petición
Se comunican porFastCGI (fastcgi_pass)HTTP (proxy_pass, reverse_proxy)
DesplegarSubir ficheros + composer installSubir un binario o una imagen
Apagado limpioLo hace php-fpmsignal.NotifyContext + srv.Shutdown

La pregunta que te vas a hacer

«Vale, pero… ¿cómo lo subo a mi servidor de verdad?»

Tienes dos caminos. Con Docker: construyes la imagen, la subes a un registro (o la construyes en el servidor) y la arrancas con docker run o docker compose, con Caddy o nginx delante. Sin Docker: compilas para Linux en tu máquina (GOOS=linux GOARCH=amd64 go build ./cmd/tareas), copias el binario con scp y lo dejas como servicio de systemd, que lo arranca al encender y le manda SIGTERM al parar.

Para profundizar:

Hora de practicar

Retos · 0/3 resueltos

Reto 1 de 3

La configuración con valores por defecto

Completa ConfigDesdeEntorno(getenv func(string) string) (Config, error): lee PUERTO (por defecto "8080") y RUTA_BD (por defecto "tareas.db"). Si PUERTO no es un número entre 1 y 65535, devuelve un error. En el programa la llamarás con os.Getenv. Es el getenv("PUERTO") ?: "8080" de PHP, con validación.

Al pulsar Comprobar, unos tests ocultos prueban tu código con el compilador oficial de Go.

Gomain.go · editable

Resumen

Lo que te llevas de esta lección

  1. go test ./... prueba todas las capas, cada una con su doble: memoria, :memory: o httptest (en PHP, vendor/bin/phpunit).
  2. signal.NotifyContext + srv.Shutdown con un ctx nuevo y con plazo: apagado sin cortar a nadie (en PHP lo hace php-fpm).
  3. La configuración, por variables de entorno con un valor por defecto (en PHP, getenv() y el .env).
  4. Dockerfile multi-stage con CGO_ENABLED=0 y distroless: una imagen de pocos megas (en PHP, PHP + php-fpm + extensiones).
  5. Caddy o nginx delante con reverse_proxy/proxy_pass hacia 127.0.0.1:8080 (en PHP, fastcgi_pass hacia php-fpm).

Para recordarlo: «Prueba, Para, Empaqueta, Publica»

PPrueba
go test ./...
PPara bien
srv.Shutdown(ctx)
EEmpaqueta
docker build
PPublica
reverse_proxy 127.0.0.1:8080

El camino de tu app de tareas hasta Internet: Prueba todas las capas, sabe Pararse sin cortar a nadie, se Empaqueta en una imagen mínima y se Publica detrás de un proxy con HTTPS.