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
Configuring the Server
Environment Variables
Running the Server
Proxying behind NGINX
Configuring the Server Daemon

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

NAME	TYPE	DESCRIPTION
`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

NAME	DESCRIPTION
`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.