browser

An Alpine Linux package repository proxy with a simple WebUI

Balrog is a lightweight Alpine Linux package repository UI and Proxy made to ease the distribution of privately built packages in a company network. Its goal is to be simple to use and deploy while providing enough information about what is currently served.

Features

• Host your own APK Repository from multiple backends (filesystem or AWS S3)
• Compatible with multiple repository branch to support multiple Alpine Linux version or distribute testing packages
• List and search packages and versions in a repository branch with the built-in UI
• Serve extra static files if needed (useful to provide standard assets when building a Docker container for example)

Screenshots

Install

Balrog is currently only packaged as a Docker container but can be built and deployed manually on most system using Go 1.8+ and NPM.

You can get the packaged container on the DockerHub and fetch it locally using:

docker pull blippar/balrog

Getting started with Docker

The easiest way to run Balrog is using Docker, this is done by just creating a configuration file and running the container with the right options.

In this example we will be using config.docker.json as our config file, this files contains everything needed to host an APK Repository from your filesystem but assumes a number of things:

• that your repository folder (the generated packages folder from abuild) is available locally at /opt/apk/packages with a main repository branch created
• that your public signing key (used to sign your packages and APKINDEX) is available at /opt/apk/.abuild/builder.rsa.pub

In order to start host your Repository UI at localhost:8000 run the following commands:

docker pull blippar/balrog
docker run --restart=always \
           --volume "./config.docker.json:/app/config.json:ro" \
           --volume "/opt/apk/packages:/data/packages:ro" \
           --volume "/opt/apk/.abuild/builder.rsa.pub:/data/packages/builder.rsa.pub" \
           -p 8000:8000 blippar/balrog

Configuration

Usage

Usage: balrog [--config CONFIG]

Options:
  --config CONFIG, -c CONFIG
                         path to your config file [env: BALROG_CONFIG] [default: config.json]
  --help, -h             display this help and exit
  --version              display version and exit

Configuration file

Balrog can only be configured using a JSON configuration file (config.json in the current working directory by default), this configuration file looks like the following document:

{
  "title": "My APK Repository",
  "http": {
    "addr": "0.0.0.0:8000",
    "templates": "templates/*.html.tmpl",
    "dist": "dist/"
  },
  "storage": {
    "type": "filesystem",
    "filesystem": {
      "prefix": "/data/packages",
      "cache":  60
    },
    "minio": {
      "endpoint":    "s3.amazonaws.com",
      "access_key":  "AKIAIOSFODNN7EXAMPLE",
      "private_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
      "region":      "us-west-2",
      "ssl":         true,
      "bucket":      "my-aports",
      "prefix":      "path/to/my/root"
    }
  },
  "repositories": [
    {
      "name": "main",
      "available_arch": ["x86","x86_64","armhf", "aarch64","ppc64le","s390x"],
      "storage_prefix": "main",
      "public_keys":[
        "[email protected]"
      ]
    }
  ],
  "static": [
    {
      "web_prefix": "assets",
      "storage_prefix": "my_assets"
    }
  ]
}

Each section of this document configures a different part of balrog, following is a quick run-down of what each section does and what is expected for each of those:

Root

http

storage

storage.filesystem

storage.minio

repository

static

Development

In order to build balrog you will first need to make sure that you have Go 1.8+ installed, we do commit all assets and if you are not working with it you should not need anything else.

From there all elements of Balrog can be built via a Makefile at the root of this repository, available rules are the followings:

Using this Makefile you will have access to the following rules:

• make balrog: build a binary for your current system under bin/balrog
• make static: build a static binary targeted at Linux based system under bin/balrog
• make assets: minify all assets needed for Balrog's UI (require NodeJS 6+)
• make all: build the binary for your current system under bin/balrog then minify all assets (require NodeJS 6+)
• make docker: build the blippar/balrog Docker container (tagged with the current version)
• make test: test balrog source code using go test -cover
• make lint: lint balrog source code using gometalinter
• make clean: remove all files that would be created by make balrog

If you want to make any change to the Javascript or CSS assets used in Balrog (other than the ones included in the templates/ folder) you will need to have NodeJS 6+ installed and run npm install before being able to rebuild the asset collection.

If any change is done, or extra assets need to be included you might need to update Gulpfile.js and run either make assets (which will use gulp from node_modules) or use gulp directly, here is the list of exposed rules in our gulpfile.js:

• gulp build: cleanup previous build, then concat and minify JS and CSS assets as well as move the necessary fonts to the dist folder
• gulp scripts: concat and minify all JS assets to the dist folder
• gulp styles: concat and minify all CSS assets to the dist folder
• gulp fonts: copy the necessary fonts to the dist folder
• guild clean: cleanup the dist folder`

Using those 2 tools you should be able to build and extend Balrog functionality and UI as you wish, just remember to create your own configuration file pointing to a local AlpineLinux repository to be able to test it properly.

Credits

Thanks to Malenea for his awesome work on the logo.

Balrog's logo is licensed under the Creative Commons Attribution 4.0 International License and was widely inspired on the original Go gopher designed by Renee French.