Server

The djinn-server is the primary component through which users would interact with the CI server. This handles serving the UI and API endpoints for the server. All assets served by the server are compiled into the binary itself, so there is no need to worry about where assets will exist on disk.

External Dependencies

Detailed below are the software dependencies that the server needs in order to start and run,

DEPENDENCY REASON
PostgreSQL Primary data store for the server.
Redis Data store used as the build queue, and for storing session data.
SMTP Server Used for sending emails on build failures.

Configuring the Server

Server parameters
NAMETYPEDESCRIPTION

host

string

The host on which the server will be running on. This will be used for OAuth redirects and setting the endpoint to which webhooks are sent. This can either be an IP address or an FQDN, though it is recommended to be the latter.

drivers

string[]

The list of drivers supported on the server. This should match what is in the server configuration.

net

object

Configuration details about how the server should be served over the network.

net.listen

string

The address that should be used to listen on.

net.write_timeout

duration

The maximum duration before timing out writes of a response, set to 0s for no timeout.

net.read_timeout

duration

The maximum duration before timing out reads of a request. Set to 0s for no timeout.

net.tls.cert

string

The path to the certificate to use when serving over TLS.

net.tls.key

string

The path to the key to use when serving over TLS.

crypto

object

Configuration settings for generating names for artifacts.

crypto.hash

string

The hash key used to authenticate values using HMAC. This must be either 32 or 64 characters in length.

crypto.block

string

The block key used for encrypting data. This must be either 16, 24, or 32 characters in length.

crypto.salt

string

Salt the is used to generate secret.

crypto.auth

string

The key used to protect against CSRF attacks. This must be 32 characters in length.

database

object

Provides connection information to the PostgreSQL database.

database.addr

string

The address of the PostgreSQL server to connect to.

database.name

string

The name of the database to use.

database.username

string

The name of the database user.

database.password

string

The password of the database user.

database.tls

object

TLS configuration for connecting via TLS.

database.tls.ca

string

Path to the CA root to use.

database.tls.cert

string

Path to the certificate to use.

database.tls.key

string

Path to the key to use.

redis

object

Providers connection information to the Redis database.

redis.addr

string

The address of the Redis server to connect to.

redis.password

string

The password used if the Redis server is password protected.

smtp

object

Provides connection innformation to an SMTP server for sending emails.

smtp.addr

string

The address of the SMTP server.

smtp.ca

string

The path to the root CA if connecting via TLS.

admin

string

The email address to be used in the From field of emails that are sent.

username

string

The username for authentication.

pasword

string

The password for authentication.

store label

object

Configuration parameters for each of the file stores the server uses. The label will be the store type, one of:

  • artifacts
  • images
  • objects

there must be a store configuration block for each.

store.type

string

The type of the store to use. Must be file.

store.path

string

The location where the files are.

store.limit

int

The maximum size of files being stored. Set to 0 for no limit.

provider label

object

Configuration parameters for reach third-party provider you want to integrate with, where the label is the name of that provider. As of now, only github, and gitlab are supported.

provider.secret

string

The secret used to authenticate incoming webhooks from the provider.

provider.client_id

string

The OAuth client ID of the provider.

provider.client_secret

string

The OAuth client secret of the provider.

EXAMPLE

pidfile "/var/run/djinn/server.pid"

log info "/var/log/djinn/curator.log"

host "https://djinn-ci.com"

drivers [
    "docker",
    "qemu-x86_64",
]

net {
    listen ":443"

    tls {
        cert "/var/lib/ssl/server.crt"
        key  "/var/lib/ssl/server.key"
    }
}

crypto {
    hash  "1a2b3c4d5e6f7g8h1a2b3c4d5e6f7g8h"
    block "1a2b3c4d5e6f7g8h"
    salt  "1a2b3c4d5e6f7g8h"
    auth  "1a2b3c4d5e6f7g8h1a2b3c4d5e6f7g8h"
}

database {
    addr "localhost:5432"
    name "djinn"

    username "djinn_server"
    password "secret"
}

redis {
    addr "localhost:6379"
}

smtp {
    addr "smtp.example.com:587"

    ca "/etc/ssl/cert.pem"

    admin "no-reply@djinn-ci.com"

    username "postmaster@example.com"
    password "secret"
}

store artifacts {
    type "file"
    path "/var/lib/djinn/artifacts"
}

store images {
    type "file"
    path "/var/lib/djinn/images"
}

store objects {
    type  "file"
    path  "/var/lib/djinn/objects"
    limit 5242880 
}

provider github {
    secret "123456"

    client_id     "..."
    client_secret "..."
}

provider gitlab {
    secret "123456"

    client_id     "..."
    client_secret "..."
}

Environment Variables

NAMEDESCRIPTION

DJINN_API_DOCS

URL to the API documentation. This link is rendered in the sidebar, if set.

DJINN_API_SERVER

URL to the API server. This is used when emitting webhook events to ensure the links in payload events point back to the API.

DJINN_USER_DOCS

URL to the user documentation. This link is rendered in the sidebar, if set.

Running the Server

To run the server simply invoke the djinn-server binary. There are three flags that can be given to the djinn-server binary.

  • -config - This specifies the configuration file to use, by default this will be djinn-server.conf.

  • -api - This tells the server to only serve the REST API endpoints.

  • -ui - This tells the server to only serve the UI endpoints.

If you do not specify either the -api, or -ui flag then both groups of endpoints will be served. The REST API endpoints will be served under the /api prefix,

Serving both the UI and API

$ djinn-server -config /etc/djinn/server.conf

Serving just the API

$ djinn-server -config /etc/djinn/server.conf -api

Serving just the UI

$ djinn-server -config /etc/djinn/server.conf -ui

Proxying behind NGINX

It is recommended that you deploy Djinn CI behind an NGINX proxy. This will give you more fine grained control over any timeouts that may occur when uploading/downloading build images. An example NGINX configuration can be found in the dist directory.

In the future, this may no longer be necessary should net/http support configuring read/write timeouts on a per handler basis, see go/golang/issues/16100.

Configuring the Server Daemon

The dist directory contains files for running the Djinn Server as a daemon on Linux systems that use systemd and SysVinit for daemon management. Use whichever suits your needs, and modify accordingly.

If deploying to a Linux system that uses systemd, then be sure to run systemctl daemon-reload upon placement of the service file.