ghdeploy

README

ghdeploy

Package ghdeploy provides an opinionated deployment process using GitHub & systemd.

Documentation

Overview

Package ghdeploy provides an opinionated deployment process using GitHub & systemd.

It is meant for single instance web servers, and not useful if you're running a fleet of web servers.

Requirements

• You are using a blue/green deployment strategy. This essentially means you will have some server in the front (haproxy, caddy, nginx etc) that will choose between the blue or the green instance, whichever is available.

• You are using Github releases. It is expected the release upload a single file, which should be a tarball.

• You are using systemd units to run your service. This should be a template unit, so the same unit is used for the blue and green instances.

Procedure

• See example repo for how this should be setup.

• Configure your Github webook to hit the endpoint you have configured.

• Configure your Github webook and the deployer with the hook secret.

Index

• type Deployer
  • func New(options ...Option) (*Deployer, error)
  • func (d *Deployer) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type Option
  • func EmailClient(client *mail.Dialer) Option
  • func EmailFrom(addr string) Option
  • func EmailTo(addr string) Option
  • func EnableDirectHandler(enable bool) Option
  • func GithubAccount(account string) Option
  • func GithubHookSecret(secret string) Option
  • func GithubRepo(repo string) Option
  • func GithubToken(token string) Option
  • func HealthCheckPath(path string) Option
  • func HealthCheckProtocol(protocol string) Option
  • func HealthCheckTimeout(timeout time.Duration) Option
  • func PortBlue(port int) Option
  • func PortGreen(port int) Option
  • func ReleasesDir(dir string) Option
  • func SystemdServiceName(name string) Option

Types

type Deployer

type Deployer struct {
	// contains filtered or unexported fields
}

Deployer handles deployment of new releases.

func New

func New(options ...Option) (*Deployer, error)

New creates a new deployer. See package documenation for more.

func (*Deployer) ServeHTTP

func (d *Deployer) ServeHTTP(w http.ResponseWriter, r *http.Request)

type Option

type Option func(*Deployer)

Option configures the Deployer.

func EmailClient

func EmailClient(client *mail.Dialer) Option

EmailClient configures the email client used to send success or failure emails on deployment.

func EmailFrom

func EmailFrom(addr string) Option

EmailFrom configures who the emails come from.

func EmailTo

func EmailTo(addr string) Option

EmailTo configures who the emails go to.

func EnableDirectHandler

func EnableDirectHandler(enable bool) Option

EnableDirectHandler enables a second handler under the path /direct/ that accepts a POST request with a `release_tag` parameter and triggers the deploy process. This is disabled by default, as it is an insecure endpoint. You may enable this at your discretion.

This can be handy to quickly deploy a different release, and can be invoked as such:

curl http://myapp.com/webhook/github/direct/ -F release_tag=v42

func GithubAccount

func GithubAccount(account string) Option

GithubAccount configures the Github account.

func GithubHookSecret

func GithubHookSecret(secret string) Option

GithubHookSecret provides the hook secret, if one is set. Leaving this blank will disable hook validation.

func GithubRepo

func GithubRepo(repo string) Option

GithubRepo configures the Github repo.

func GithubToken

func GithubToken(token string) Option

GithubToken provides the Github API token.

func HealthCheckPath

func HealthCheckPath(path string) Option

HealthCheckPath configures the health check path. The default is /.

func HealthCheckProtocol

func HealthCheckProtocol(protocol string) Option

HealthCheckProtocol must be one of tcp, http or https. The default is tcp, which simply checks for a successful connection. HTTP checks for a 200 response on the configured path.

func HealthCheckTimeout

func HealthCheckTimeout(timeout time.Duration) Option

HealthCheckTimeout specifies the duration we wait to check if a new service is healthy. The default is 30s.

func PortBlue

func PortBlue(port int) Option

PortBlue is the first of two ports. The default is 8000.

func PortGreen

func PortGreen(port int) Option

PortGreen is the second of two ports. The default is 8001.

func ReleasesDir

func ReleasesDir(dir string) Option

ReleasesDir is where the last two releases will be stored. The default is ~/.local/<service-name>.

func SystemdServiceName

func SystemdServiceName(name string) Option

SystemdServiceName configures the base name of the unit. Defaults to GithubRepoName. It is expected this will be a template unit. See package documentation for more.