Skip to main content

Configure a Dedicated Redis Port

Overview​

Appcircle runners send live build logs to the Appcircle server through Redis. On an Appcircle server configured with HTTPS, Redis shares port 443 with the web services. The front proxy of the server reads the domain name of every new connection and forwards it internally, either to the web services or to Redis. This internal hop costs proxy CPU on every connection, including the web and API traffic that never goes to Redis.

You can give Redis its own port instead. Port 443 then carries only web traffic, the internal hop is removed, and the front proxy handles more traffic with the same resources.

The default configuration is suitable for most installations. Consider a dedicated Redis port when your Appcircle server handles high request volumes, for example CodePush updates rolled out to a large number of devices at the same time.

info

This feature is included in the Appcircle server package version 3.34.0 or later.

info

This page applies to Appcircle servers configured with HTTPS (external.scheme: https). With HTTP, Redis already uses its own port (6379 by default), so no change is needed.

What Changes​

  • Redis is served with TLS on the port you choose, using the same SSL certificate as the rest of the Appcircle server.
  • Redis is no longer reachable on port 443.
  • Every Appcircle runner must connect to Redis on the new port.

Prerequisites​

  • Choose a port that is free on the Appcircle server and allowed by your security policy. The examples on this page use 6380.

  • Allow the Appcircle runners to connect directly to the Appcircle server on that port.

    • If there is no load balancer in front of the Appcircle server, allow the port in your firewall in the same way as the existing runner access to the Appcircle server.

    • If a load balancer is in front of the Appcircle server, make the redis subdomain (for example redis.appcircle.spacetech.com) resolve to the IP address of the Appcircle server instead of the load balancer, and allow the runners to reach the Appcircle server on the new port in your firewall. Runners connect to Redis by this host name, so their Redis traffic goes straight to the Appcircle server while web traffic on port 443 keeps using the load balancer. After this change the redis subdomain is only used for Redis, so pointing it to the Appcircle server does not affect any other service.

      caution

      If your DNS uses a wildcard record (for example *.appcircle.spacetech.com) that points to the load balancer, add a separate record for the redis subdomain. A specific record takes precedence over the wildcard.

  • If the Appcircle server uses firewalld, open the port on the server:

    sudo firewall-cmd --add-port=6380/tcp --permanent
    sudo firewall-cmd --reload

  • The SSL certificate does not change. It already covers the redis subdomain, which the Appcircle server requires.

tip

With rootless Podman, ports above 1024 can be published directly, so the new port does not need a port redirection like 443 does.

Configuring the Appcircle Server​

caution

Be aware that this process will cause downtime since it requires a restart of the Appcircle server.

  1. Log in to your Appcircle server via SSH or a remote connection.

  2. Change to the directory containing the Appcircle server configuration.

    cd appcircle-server

  3. Open the global.yaml file in a text editor.

    info

    The spacetech in the example codes below are example project name.

    Please find your own project name and replace spacetech with your project name.

    To see projects, you can check the projects directory.

    ls -l ./projects
    vi ./projects/spacetech/global.yaml

  4. Add the port key under webEventRedis.external.

    caution

    If the webEventRedis entry already exists in your global.yaml file, for example with a custom subdomain, add the port key to the existing entry instead of creating a new one.

    webEventRedis:
      external:
        port: 6380

  5. After saving the configuration changes, restart your Appcircle server to apply the new settings.

    • Shutdown Appcircle server.
    ./ac-self-hosted.sh -n "spacetech" down
    • Apply configuration changes.
    ./ac-self-hosted.sh -n "spacetech" export
    • Boot Appcircle server.
    ./ac-self-hosted.sh -n "spacetech" up
    tip

    You should check the status of the Appcircle server after boot for any possible errors.

    ./ac-self-hosted.sh -n "spacetech" check

Updating the Appcircle Runners​

After the Appcircle server restarts, runners that still use port 443 cannot reach Redis. Their builds keep running, but live build logs are not streamed until the runner is updated. Update every runner right after the Appcircle server.

  1. On the runner machine, change to the directory of the Appcircle runner, where appsettings.json is located.

  2. Set ASPNETCORE_REDIS_STREAM_ENDPOINT to the Redis subdomain of your Appcircle server with the new port.

    echo "$(jq '.ASPNETCORE_REDIS_STREAM_ENDPOINT="redis.appcircle.spacetech.com:6380,ssl=true"' appsettings.json)" > appsettings.json

  3. Restart the runner service so that it uses the new endpoint.

    ./ac-runner service -c restart

    For more details, see managing the self-hosted runner service.

info

If your runners are macOS virtual machines created from a base image, update appsettings.json in the base runner VM as well, so that new runner VMs use the new port. See configuring the runner service on the runner VM.

Verifying the Configuration​

  1. From a runner machine, check that Redis answers on the new port with TLS.

    openssl s_client -connect redis.appcircle.spacetech.com:6380 -servername redis.appcircle.spacetech.com </dev/null

    The command should complete the TLS handshake and show the SSL certificate of your Appcircle server. A connection timeout usually means the port is blocked between the runner and the Appcircle server.

  2. Start a build and confirm that its live logs appear on the Appcircle dashboard.

Reverting to the Default Configuration​

  1. Remove the port key under webEventRedis.external in the global.yaml file.

  2. Restart your Appcircle server.

    • Shutdown Appcircle server.
    ./ac-self-hosted.sh -n "spacetech" down
    • Apply configuration changes.
    ./ac-self-hosted.sh -n "spacetech" export
    • Boot Appcircle server.
    ./ac-self-hosted.sh -n "spacetech" up
    tip

    You should check the status of the Appcircle server after boot for any possible errors.

    ./ac-self-hosted.sh -n "spacetech" check

  3. Set ASPNETCORE_REDIS_STREAM_ENDPOINT back to port 443 on every runner and restart the runner service.

    echo "$(jq '.ASPNETCORE_REDIS_STREAM_ENDPOINT="redis.appcircle.spacetech.com:443,ssl=true"' appsettings.json)" > appsettings.json
    ./ac-runner service -c restart

  4. If you pointed the redis subdomain to the IP address of the Appcircle server because of a load balancer, point it back to the load balancer, since Redis is served on port 443 again.

info

The Appcircle DMZ server does not handle Redis traffic, so this configuration does not require any change on the DMZ server.

Need help?​

Get help from Appcircle's support team, or see how others are using Appcircle by joining our Slack Channel.

join.slack.com
No description available
join.slack.com
Preview of join.slack.com