autotls

README

autotls

Support Let's Encrypt for a Go server application.

example

example for 1-line LetsEncrypt HTTPS servers.

package main

import (
  "log"
  "net/http"

  "github.com/gin-gonic/autotls"
  "github.com/gin-gonic/gin"
)

func main() {
  r := gin.Default()

  // Example handler
  r.GET("/ping", func(c *gin.Context) {
    c.String(http.StatusOK, "pong")
  })

  // Start HTTPS server with automatic Let's Encrypt certificate management and HTTP-to-HTTPS redirection.
  // The server runs until interrupted and shuts down gracefully.
  log.Fatal(autotls.Run(r, "example1.com", "example2.com"))
}

example for custom autocert manager.

package main

import (
  "log"
  "net/http"

  "github.com/gin-gonic/autotls"
  "github.com/gin-gonic/gin"
  "golang.org/x/crypto/acme/autocert"
)

func main() {
  r := gin.Default()

  // Example handler
  r.GET("/ping", func(c *gin.Context) {
    c.String(http.StatusOK, "pong")
  })

  // Advanced: Use a custom autocert.Manager for certificate management.
  // This allows for custom cache location, host policy, and other settings.
  m := autocert.Manager{
    Prompt:     autocert.AcceptTOS,
    HostPolicy: autocert.HostWhitelist("example1.com", "example2.com"),
    Cache:      autocert.DirCache("/var/www/.cache"),
  }

  // Start HTTPS server with the custom autocert.Manager and HTTP-to-HTTPS redirection.
  log.Fatal(autotls.RunWithManager(r, &m))
}

example usage for graceful shutdown with custom context.

package main

import (
  "context"
  "log"
  "net/http"
  "os/signal"
  "syscall"

  "github.com/gin-gonic/autotls"
  "github.com/gin-gonic/gin"
)

func main() {
  // Create a context that listens for interrupt signals (SIGINT, SIGTERM) from the OS.
  // This enables graceful shutdown of the HTTPS server.
  ctx, stop := signal.NotifyContext(
    context.Background(),
    syscall.SIGINT,
    syscall.SIGTERM,
  )
  defer stop()

  r := gin.Default()

  // Example handler
  r.GET("/ping", func(c *gin.Context) {
    c.String(http.StatusOK, "pong")
  })

  // Start HTTPS server with automatic Let's Encrypt certificate management,
  // HTTP-to-HTTPS redirection, and graceful shutdown support.
  // The server will shut down cleanly when the context is cancelled.
  log.Fatal(autotls.RunWithContext(ctx, r, "example1.com", "example2.com"))
}

Documentation

Overview

Package autotls support Let's Encrypt for a Go server application.

package main

import (
  "log"

  "github.com/gin-gonic/autotls"
  "github.com/gin-gonic/gin"
)

func main() {
  r := gin.Default()

  // Ping handler
  r.GET("/ping", func(c *gin.Context) {
    c.String(200, "pong")
  })

  log.Fatal(autotls.Run(r, "example1.com", "example2.com"))
}

Index

• Variables
• func Run(r http.Handler, domain ...string) error
• func RunWithContext(ctx context.Context, r http.Handler, domain ...string) error
• func RunWithManager(r http.Handler, m *autocert.Manager) error
• func RunWithManagerAndTLSConfig(r http.Handler, m *autocert.Manager, tlsc *tls.Config) error

Variables

var ReadHeaderTimeout = 3 * time.Second

ReadHeaderTimeout is the maximum duration for reading the headers of the request.

Functions

func Run

func Run(r http.Handler, domain ...string) error

Run starts an HTTPS server with automatic Let's Encrypt certificate management and HTTP-to-HTTPS redirection. The server runs until interrupted and shuts down gracefully.

r:      HTTP handler for HTTPS requests.
domain: One or more domain names for certificate issuance.

func RunWithContext

func RunWithContext(ctx context.Context, r http.Handler, domain ...string) error

RunWithContext starts an HTTPS server with automatic Let's Encrypt certificate management, HTTP-to-HTTPS redirection, and graceful shutdown support. The provided context controls the server's lifetime and shutdown.

ctx: Context for graceful shutdown.
r:   HTTP handler for HTTPS requests.
domain: One or more domain names for certificate issuance.

func RunWithManager

func RunWithManager(r http.Handler, m *autocert.Manager) error

RunWithManager starts an HTTPS server using a custom autocert.Manager for certificate management, with HTTP-to-HTTPS redirection. Useful for advanced autocert configuration.

r: HTTP handler for HTTPS requests.
m: Custom autocert.Manager instance.

func RunWithManagerAndTLSConfig

func RunWithManagerAndTLSConfig(r http.Handler, m *autocert.Manager, tlsc *tls.Config) error

RunWithManagerAndTLSConfig starts an HTTPS server using a custom autocert.Manager and custom tls.Config, with HTTP-to-HTTPS redirection.

r:    HTTP handler for HTTPS requests.
m:    Custom autocert.Manager instance.
tlsc: Custom TLS configuration.