Run Your Own Zappr
So, you want to run your own Zappr because you too have GitHub Enterprise—or you just don't want to use Zappr Opensource for whatever reason. That's fine. Here's what you need (Mandatory/Recommended/Optional):
- (M) A GitHub. This might be a GitHub Enterprise instance, or you can use the public GitHub.
- (M) A PostgreSQL database.
- (M) Servers on which you can run Docker containers or JavaScript.
- (R) A proper/not self-signed certificate, so that GitHub can verify the SSL connection.
- (O) A load balancer, if you want to run Zappr on multiple nodes.
- (O) For encrypting tokens stored in the database, we use KMS. If that's not an option, you will have to implement the EncryptionService interface and make sure it can be created via the EncryptionServiceCreator.
Got it! I have everything now. What next?
We need to build the code!
All configuration is contained in a single file config/config.yaml
. Put the necessary configuration options in there,
they are explained in the next section. Remember you can override them with environment variables as you wish.
We host a Zappr base image at registry.opensource.zalan.do/opensource/zappr
, for which you only need to add your configuration.
See Dockerfile.external
in the repository as an example.
Configuration options
Zappr provides a whole lot of configuration options for flexibility.
Github
GITHUB_CLIENT_ID
: Client ID of your OAuth application in GithubGITHUB_CLIENT_SECRET
: Client secret of your OAuth application in GithubGITHUB_HOOK_SECRET
: Secret value used to verify only Github calls ZapprGITHUB_UI_URL
: URL to Github web user interfaceGITHUB_API_URL
: URL to Github APIHOOK_URL
: Optional explicit webhook url to use for receiving webhooks from Github. Required if there is a proxy or load balancer that receives traffic from the internet and forwards it to Zappr.
Server
SESSION_SECRET
: Secret to use for session cookieHOST_ADDR
: Address of Zappr itself (used e.g. as redirect URI in OAuth flow)APP_PORT
: Port on which Zappr runsMETRICS_PORT
: Port on which metrics are servedMETRICS_ENABLED
: Whether to serve metrics or notSTATIC_DIR
: Where to find static assetsLOG_LEVEL
: Desired amount of logging, can beinfo
ordebug
Database (Postgres)
DB_HOST
: DNS/IP of database serverDB_PORT
: Port where database server listens, usually5432
DB_USER
: Database user, might bepostgres
or you create a different user (recommended)DB_PASS
: Password for database userDB_NAME
: Which database to use
Encryption
ENCRYPTION_ENGINE
:~
for none,kms
for encryption with AWS KMS
KMS
ENCRYPTION_KEY
: ARN of the key to use for encrypting access tokensKMS_REGION
: Region this key is located in
Audit logs
AUDIT_SHIP_ENGINE
: Where to ship the audit logs to. Can beconsole
,file
orzalando-audit-trail
(not for public use)AUDIT_TRANSFORM_ENGINE
: How the shipped logs should look like. Can beidentity
orzalando-audit-trail
(not for public use)AUDIT_RELEVANT_ORGS
: Array of organisations that you want to audit. If it's not an array, everything will be logged.
File shipper
The file shipper uses winston.transports.File
, please look there for a more detailed documentation.
AUDIT_FILE_NAME
: Filename where audit logs go to, defaults toaudit.log
AUDIT_MAX_SIZE
: Maximum size of a single audit file, defaults to 10 MBAUDIT_MAX_FILES
: How many files to keep around, defaults to 3
Zalando Audit Trail Shipper (not for public use)
AUDIT_TRAIL_API_URL
: URL of the Zalando Audit Trail API
Zappr
Don't put these in environment variables as they are expected to be objects/arrays inside the application.
VALID_ZAPPR_FILE_PATHS
: Which paths to fetch from a repository when looking for a ZapprfileVALID_PR_TEMPLATE_PATHS
: Which paths to fetch from a repository when looking for a pull request templateZAPPR_DEFAULT_CONFIG
: Default configuration. Will be used as-is if no Zapprfile is in the repository or will be merged with Zapprfile.