> ## Documentation Index
> Fetch the complete documentation index at: https://certplane.kippel.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Comenzar con Certplane

> Despliega el broker, registra tu primer host con un token de arranque y obtén un certificado TLS público de extremo a extremo en un único flujo.

Esta guía recorre toda la configuración de Certplane: ejecutar el broker, definir una política, registrar un host con su certificado de identidad e iniciar el bucle de renovación del agente. Al terminar, tu host tendrá un certificado TLS de confianza pública que se renueva automáticamente.

<Tip>
  ¿Prefieres Ansible? Salta a la [guía de roles de Ansible](/es/guides/ansible) — los roles `certplane_broker` y `certplane_agent` automatizan todo lo que aparece en esta página.
</Tip>

<Steps>
  <Step title="Requisitos previos">
    Antes de empezar:

    * **step-ca** — Una instancia de [step-ca](https://smallstep.com/docs/step-ca/) accesible desde tus hosts. Es la CA interna que emite los certificados de identidad de los agentes.
    * **Acceso a Let's Encrypt** — El broker usa ACME para obtener certificados públicos. Necesitas un correo válido para la cuenta ACME.
    * **Un proveedor DNS soportado para dns-01** — Actualmente `cloudflare` o `httpreq`. Los perfiles wildcard requieren `dns-01`.
    * **Los binarios de Certplane** — `certplane-broker` en el host del broker y `certplane-agent` en cada host gestionado. Se compilan con `make` desde el [repositorio fuente](https://github.com/TaconeoMental/Certplane).
  </Step>

  <Step title="Despliega el broker">
    Crea `/etc/certplane/broker.yml` (refleja [`examples/config/broker.yml`](https://github.com/TaconeoMental/Certplane/blob/main/examples/config/broker.yml)):

    ```yaml broker.yml theme={null}
    server:
      address: ":8443"
      tls:
        cert: /etc/certplane/broker/broker.crt
        key: /etc/certplane/broker/broker.key
        min_version: "1.2"
      mtls:
        agent_ca_bundle: /etc/certplane/ca/agent-identity-ca-bundle.crt
      read_header_timeout: 5s
      read_timeout: 10s
      write_timeout: 60s
      idle_timeout: 120s

    policy:
      path: /etc/certplane/policy.yml
      watch: false

    issuer:
      provider: acme
      acme:
        directory_url: https://acme-v02.api.letsencrypt.org/directory
        account_email: admin@example.com
        account_key: /var/lib/certplane/acme/account.key
        dns_provider: cloudflare

    secrets:
      provider: env

    store:
      driver: sqlite
      path: /var/lib/certplane/broker.db

    audit:
      enabled: true
      failure_mode: fail_open
      mirror_to_log: true

    rate_limits:
      per_identity_per_hour: 50
      per_identity_profile_per_hour: 20

    logging:
      level: info
      format: json
      destination: stdout
    ```

    `server.mtls.agent_ca_bundle` debe ser el bundle de CA que firma los certificados de identidad de tus agentes — normalmente la raíz o intermedia de `step-ca`.

    Inicia el broker:

    ```bash theme={null}
    certplane-broker -c /etc/certplane/broker.yml serve
    ```

    El broker escucha en `:8443` y exige mTLS a todo agente conectado. Referencia completa en [Configuración del broker](/es/configuration/broker).
  </Step>

  <Step title="Crea el archivo de política">
    Crea `/etc/certplane/policy.yml`:

    ```yaml policy.yml theme={null}
    version: 1

    profiles:
      public_edge_main:
        type: wildcard
        dns_names:
          - "*.example.com"
        acme:
          challenge: dns-01
          credentials: cloudflare/example-com
        renew_before: 720h

    hosts:
      edge01:
        identity: edge01.h.int.example.com
        profiles:
          - public_edge_main
    ```

    * **profiles** — Cada perfil define `type` (`wildcard` o `multi_san`), `dns_names` permitidos, opciones ACME (`acme.challenge` y `acme.credentials`) y un `renew_before` opcional.
    * **hosts** — Cada entrada mapea una etiqueta a una `identity` (el CN del certificado emitido por `step-ca`) y lista los `profiles` que ese host puede solicitar. Las peticiones a otros perfiles se rechazan.

    Valida antes de desplegar:

    ```bash theme={null}
    certplane-broker -c /etc/certplane/broker.yml policy validate --policy /etc/certplane/policy.yml
    ```

    Referencia completa en [Resumen de política](/es/policy/overview).
  </Step>

  <Step title="Registra tu primer host">
    El registro entrega al host su certificado de identidad. El agente contacta `step-ca` una vez con un token de arranque corto, genera un par ECDSA localmente y guarda `identity.crt`.

    **Genera un token de arranque** en `step-ca`:

    ```bash theme={null}
    step ca token edge01.h.int.example.com
    ```

    Escribe el token en el host en la ruta indicada por la configuración del agente (p. ej. `/etc/certplane/bootstrap-token`, modo `0600`).

    **Crea la configuración del agente** en `/etc/certplane/agent.yml` (refleja [`examples/config/agent.yml`](https://github.com/TaconeoMental/Certplane/blob/main/examples/config/agent.yml)):

    ```yaml agent.yml theme={null}
    state_dir: /var/lib/certplane/agent

    identity:
      name: edge01.h.int.example.com
      provider: step-ca
      cert: /var/lib/certplane/agent/identity.crt
      key: /var/lib/certplane/agent/identity.key
      issuer_ca_bundle: /etc/certplane/ca/agent-identity-ca-bundle.crt
      bootstrap_token: /etc/certplane/bootstrap-token
      renew_before: 8h
      warn_before: 24h
      step_ca:
        url: https://ca.int.example.com
        fingerprint: "sha256:aabbcc..."
        root_ca_bundle: /etc/certplane/ca/step-ca-root.crt
        timeout: 10s

    broker:
      url: https://certplane-broker.int.example.com:8443
      server_ca_bundle: /etc/certplane/ca/broker-server-ca-bundle.crt
      timeout: 30s

    logging:
      level: info
      format: text
      destination: stderr

    certificates:
      - name: edge-wildcard
        profile: public_edge_main
        dns_names:
          - "*.example.com"
        key:       /var/lib/certplane/agent/service.key
        cert:      /var/lib/certplane/agent/service.crt
        chain:     /var/lib/certplane/agent/service.chain.crt
        fullchain: /var/lib/certplane/agent/service.fullchain.crt
        renew_before: 720h
        reload_command: "systemctl reload traefik"
        reload_timeout: 30s
    ```

    **Ejecuta el registro:**

    ```bash theme={null}
    certplane-agent -c /etc/certplane/agent.yml enroll
    ```

    El agente genera `identity.key` localmente, construye un CSR y lo envía a `step-ca` junto con el token. Si todo va bien, `identity.crt` se escribe y el archivo del token se borra.

    <Note>
      El token de arranque se consume durante el registro y no es reutilizable. Si falla y necesitas reintentar, genera un token nuevo desde `step-ca`. Más detalle en [Registro del agente](/es/setup/agent-enroll).
    </Note>
  </Step>

  <Step title="Ejecuta el agente">
    Una vez registrado el host, ejecuta el bucle de renovación. El agente es un binario one-shot — programalo con un timer (el role de Ansible incluye uno; consulta [Ejecutar el agente](/es/setup/agent-run) para la unidad standalone).

    ```bash theme={null}
    certplane-agent -c /etc/certplane/agent.yml run
    ```

    En cada ejecución, el agente:

    1. Renueva el certificado de identidad si expira dentro de `identity.renew_before`.
    2. Para cada entrada en `certificates`:
       * Asegura una clave de servicio ECDSA local en `key` (la genera si falta, la reutiliza si existe).
       * Salta el certificado si el existente es válido y aún no entra en la ventana de `renew_before`.
       * Si no, construye un CSR con los `dns_names`, llama al broker por mTLS, valida que el bundle devuelto coincide con la clave local y con los DNS solicitados, escribe `cert`, `chain` y `fullchain`, y ejecuta `reload_command` si está definido.

    Valida la configuración y el estado en disco sin cambios:

    ```bash theme={null}
    certplane-agent -c /etc/certplane/agent.yml check
    ```
  </Step>
</Steps>

## Próximos pasos

* [Guía de roles de Ansible](/es/guides/ansible) — despliegue de producción con los roles oficiales.
* [Configuración del broker](/es/configuration/broker) y [Configuración del agente](/es/configuration/agent).
* [Resumen de política](/es/policy/overview).
* [Let's Encrypt + dns-01](/es/guides/lets-encrypt-dns).