Skip to content

Latest commit

 

History

History
150 lines (111 loc) · 6.89 KB

setup.md

File metadata and controls

150 lines (111 loc) · 6.89 KB
Raw

Server Setup

The MAYPAD frontend and backend run together in docker container allowing it to run on any infrastructure. It requires a additional MySQL database for data persistence.

Running the server

We provide a ready-to-use docker-compose file with which you can start a MAYPAD instance including a MySQL database within minutes. Note that you should use a proper MySQL database instead of the docker container for production environments and persistence.

Building yourself

  1. Clone the repo
  2. Make sure all dependencies are installed (java, maven, nodejs, docker)
  3. Install node modules cd frontend && npm install && cd ..
  4. Build the container ./build.sh --prod
  5. Copy the sample config file cp config.yaml{.sample,} and make neccessary changes to it
  6. Start MAYPAD using docker-compose up

Using pre-build docker container

  1. Replace the image for the maypad-app in the docker-compose file maypad by juliantodt/maypad
  2. Start MAYPAD using docker-compose up

Configuration

  • MAYPAD can either be configured using it's configuration file or via environment variables (MAYPAD_ followed by the full attribute name in ALL_CAPS_WITH_UNDERSCORES, e.g. MAYPAD_WEBHOOK_TOKEN_LENGTH for webhook.tokenLength).
  • The environment variable MAYPAD_HOME indicates where MAYPAD will look for the configuration file and the frontend files and defaults to /usr/share/maypad/.
  • For an example config file see config.yaml.sample
  • Note that MAYPAD will generate an encryption key for database entries under MAYPAD_HOME/security/key.dat that you should save between container restarts. The default docker-compose will take care of that.

Environment variables

Full documentation of available environment variables. If a value of one of these variables is set, it will override the value given in the config.yaml-file.

MAYPAD_HOME: Home path for MAYPAD. MAYPAD looks for the frontend, cloned repositories and the server configuration file here.

MAYPAD_WEB_SERVER_PORT: Port on which the web server runs.
MAYPAD_RELOAD_REPOSITORIES_SECONDS: Time interval in seconds in which MAYPAD refreshes the imported repositories (projects).

MAYPAD_SCHEDULER_POOL_SIZE: Sets the amount of threads available to the MAYPAD scheduler.

MAYPAD_WEBHOOK_TOKEN_LENGTH: Sets the length of the tokens inside a webhook generated by MAYPAD (e.g. webhook for reporting a successful build).

MAYPAD_MAXIMUM_REFRESH_REQUESTS_ENABLED: Set to 1 when you want to limit the amount of refresh requests in a given time interval to a given number.

MAYPAD_MAXIMUM_REFRESH_REQUESTS_SECONDS: The time interval described in MAYPAD_MAXIMUM_REFRESH_REQUESTS_ENABLED in seconds.

MAYPAD_MAXIMUM_REFRESH_REQUESTS_MAXIMUM_REQUESTS: The maximum allowed refresh requests in the time interval given by MAYPAD_MAXIMUM_REFRESH_REQUESTS_SECONDS, as described in MAYPAD_MAXIMUM_REFRESH_REQUESTS_ENABLED.

MAYPAD_LOGGING_LEVEL_ROOT: Sets the level of detail in the server console log. Accepted values are: ERROR, WARN, INFO, DEBUG, TRACE.

MAYPAD_REPOSITORY_STORAGE_PATH: Sets the path in which repositories are supposed to be cloned into.

MAYPAD_MYSQL_USER: Sets the username for the database-connection used by MAYPAD for persistence.

MAYPAD_MYSQL_PASSWORD: Sets the password for the database-connection.

MAYPAD_MYSQL_DATABASE: Sets the database name for the database-connection.

MAYPAD_MYSQL_HOST: Sets the hostname of the database-connection. This could for example be an IP-Address or a URL.

MAYPAD_MYSQL_PORT: Sets the port on which MAYPAD should listen for the database-connection.

MAYPAD_DOMAIN: Sets the domain on which MAYPAD is running. Used to construct complete webhooks.

Configuration yaml-file

MAYPAD can use a configuration file called config.yaml in the MAYPAD_HOME-directory. All keys correspond to an environment variable, which is described above. Here's a complete configuration file (also found in the repository as config.yaml.sample):

webServerPort: 8080 # Corresponds to MAYPAD_WEB_SERVER_PORT, Default: -1
reloadRepositoriesSeconds: 900 # Corresponds to MAYPAD_RELOAD_REPOSITORIES_SECONDS, Default: 900

scheduler:
  poolSize: 4 # Corresponds to MAYPAD_SCHEDULER_POOL_SIZE, Default: 2

webhook:
  tokenLength: 24 # Corresponds to MAYPAD_WEBHOOK_TOKEN_LENGTH, Default: 20

maximumRefreshRequests:
  enabled: true # Corresponds to MAYPAD_MAXIMUM_REFRESH_REQUESTS_ENABLED, Default: false
  seconds: 3600 # Corresponds to MAYPAD_MAXIMUM_REFRESH_REQUESTS_SECONDS, Default: 900
  maximumRequests: 100 # Corresponds to MAYPAD_MAXIMUM_REFRESH_REQUESTS_MAXIMUM_REQUESTS, Default: 100

logLevel: INFO #ERROR, WARN, INFO, DEBUG # Corresponds to MAYPAD_LOG_LEVEL, Default: INFO
repositoryStoragePath: /home/maypad/repositories # Corresponds to MAYPAD_REPOSITORY_STORAGE_PATH, Default: not set

mysql:
  user: maypad # Corresponds to MAYPAD_MYSQL_USER, Default: not set
  password: maypaddb # Corresponds to MAYPAD_MYSQL_PASSWORD, Default: not set
  database: maypad # Corresponds to MAYPAD_MYSQL_DATABASE, Default: not set
  host: maypad-database # Corresponds to MAYPAD_MYSQL_HOST, Default: not set
  port: 3306 # Corresponds to MAYPAD_MYSQL_PORT, Default: -1

domain: localhost # Corresponds to MAYPAD_DOMAIN, Default: not set

Webserver Configuration

You can use MAYPAD without a additional webserver, but if you want to add authorization to MAYPAD, consider proxying the requests through a webserver such as nginx and then add http basic authentication. An example configuration could look like this (note the extra nginx configuration parameters because MAYPAD uses Server-Send-Events for notifications):

server {
  listen 80 default_server;
  listen [::]:80 default_server;
  server_name demo.maypad.de;

  location / {
    proxy_pass http://maypad-app:8080/;
    add_header X-Frame-Options SAMEORIGIN;

    auth_basic "MAYPAD Demo";
    auth_basic_user_file /etc/nginx/conf.d/htpasswd;
  }

  location /sse {
    proxy_pass http://maypad-app:8080/sse;
    add_header X-Frame-Options SAMEORIGIN;
    proxy_http_version 1.1;
    proxy_set_header Connection "";
    add_header Transfer-Encoding: chunked;
    add_header X-Accel-Buffering: no;
    proxy_buffering off;
  }
}

The docker-compose in this case could look like this (using a external MySQL database):

version: '3'

services:
  app:
    image: juliantodt/maypad
    container_name: maypad-app
    restart: 'no'
    volumes:
    - ./config.yaml:/usr/share/maypad/config.yaml
    - ./repos:/home/maypad/repositories
    - ./security:/usr/share/maypad/security
    environment:
    - SPRING_PROFILES_ACTIVE=prod
    expose:
    - 8080
  nginx:
    image: nginx
    container_name: maypad-nginx
    restart: always
    ports:
    - 80:80
    volumes:
    - ./nginx:/etc/nginx/conf.d

Addtional configurations?

Using MAYPAD on a different infrastructure (AWS, Kubernetes, etc.)? Open a Pull-Request and add your configuration here for others to see.