Set up the BlackBox Hub Local Cache Server


The BlackBox Hub Local Cache Server allows studios to add a download cache to BlackBox Hub. This greatly reduces the download needs of a studio during development build distribution. It does this by intelligently caching initial downloads of builds, then intercepting further downloads of the same build from S3 and providing them from the local cache instead.

Before you begin

Hardware specifications

To set up the BlackBox Hub Local Cache Server you need at least the following:

  • Memory - 4 GB

  • CPU - 2 cores  

  • Fast SSD for cache storage (Nvme M.2)

  • Fast Ethernet network

Software requirements

Before you can set up the BlackBox Hub local cache server, you need to do the following:

  • Install Ubuntu/Ubuntu Server >= 20.04 (currently not tested with other OS versions)

  • Install Docker >= v20.10 (API version 1.41)

  • Install Local Cache Installer (by request from AccelByte)

  • [Optional ] Prepare a directory for the cache target. This can be a folder or mounted disk drive (e.g /mnt/volume1/cache )

  • [Optional ]Set the permissions of the cache target as 755

  • Set up your firewall to allow the machine to listen to a specific port (e.g 8080)


Install the Local Cache Server

There are two ways to install the Local Cache Server; interactive mode and command line mode. The installation steps for both of these are described below.

To make the setup file executable in terminal, you need to run sudo chmod +x local-cache-setup-ubuntu-v1.3.0 by typing it on the command line before starting the installation

Install the Local Cache Server in Interactive Mode

Install the Local Cache Server as follows:

  1. Execute the following command:

1 ./local-cache-setup-ubuntu-v1.3.0 install -i
  1.  Complete the required information.

    • Cache Retention: how long to keep the cache (default: 12h)

    • Port: the local cache server port to be served (default: 80)

    • Number of workers: how many workers to serve (default: 8, usually same as the number of CPU cores)

    • Cache Mount: the location of your cache directory (default: none) (optional field)

    • Namespace: the namespace of your game

    • GameIDs: optional field - this is the id you used during integration with BlackBox.

1 2 3 4 5 6 Cache Retention(12h) : Port(80) : Number of worker(8) : Cache Mount() : <CACHE_DIRECTORY> (optional) Namespace() : <YOUR_NAMESPACE> (required) GameIDs() : <PRIORITY_GAME_ID> (optional)

Installation will complete.

1 2 3 4 5 2021/12/21 15:23:04 prepare docker... 2021/12/21 15:23:04 writing config file... 2021/12/21 15:23:04 copy executable.... 2021/12/21 15:23:04 installing service... 2021/12/21 15:23:04 blackbox local cache installed

Install the Local Cache Server in command line mode

To install the Local Cache Server in command line mode, enter the fields and their values on the command line as follows:

  • -p, --port: Local cache server port to be served

  • -w, --worker Local cache server worker

  • -r, --retention Local cache server retention

  • -c, --cache-mount Local cache mount directory
    for example:

    1 2 3 #!/bin/sh ./local-cache-setup-ubuntu-v1.3.0 install --port 8080 --worker 8 --retention 12h --cache-mount /home/cache

Start the Local Cache Server

You do not need to start the Local Cache Server. It starts automatically after the installation process is successful.

Check the status of the Local Cache Server

To check the status of the Local Cache Server:

  1. Execute one of the following:

    1 bblocalcache status


    1 systemctl status bblocalcache
  2. Make sure the service is running (if it’s not running repeat the install procedure).

    1 2 3 4 5 6 7 8 9 10 2021/12/23 10:50:49 service is running. / /docker-entrypoint.d/ is not empty, will attempt to perform configuration / Looking for shell scripts in /docker-entrypoint.d/ / Launching /docker-entrypoint.d/ info: Getting the checksum of /etc/nginx/conf.d/default.conf info: Enabled listen on IPv6 in /etc/nginx/conf.d/default.conf / Launching /docker-entrypoint.d/ Running envsubst on /etc/nginx/templates/nginx.conf.template to /etc/nginx/nginx.conf / Launching /docker-entrypoint.d/ / Configuration complete; ready for start up

Check that the Local Cache Server is successfully installed and running

To check if your Local Cache Server is successfully installed and running:

  1. Open BlackBox Hub on your computer.

  2. Click the Settings icon on the top right corner.

  3. Fill the proxy-cache text field with your Local Cache Server IP address.

  4. Click the Verify button.
    When the IP address is found, a green Verified message displays.

  5. Click the Save Changes button.

Uninstalling a Local Cache Server

You can remove a Local Cache Server using the script provided:

  1. Download the uninstall script by running the following command:

    1 curl -o ./
  2. Run the following command to allow you to execute the file from a terminal:

    1 chmod +x ./
  3. Run the command from the terminal:

    1 sudo ./


Local Cache Server is not working, I tried to use it to download the same binary twice with the same internet speed

  1. Check your Local Cache Server, make sure it allows user systemd-journal to rename the file.

  2. Try to give your Local Cache Server folder 777 permission.

  3. Change your Local Cache Server folder owner user to something other than the root.


Cannot connect to the Local Cache Server

Check your firewall, make sure it has access to the port that you specified during the installation process. If the firewall doesn’t have access, whitelist the port on the firewall setting.


Download speed is still slow

Download speed can be affected by a number of factors:

  1. Make sure you have a fast SSD on the server for the cache storage.

  2. Make sure the connection between your computer and the Local Cache Server is using Gigabit Ethernet (1 Gbps).

  3. Try to increase your memory on the Local Cache Server.