Skip to main content
Version: 0.10.x

Deployment

Supported OS​

Lunar Proxy is designed to run on Linux and macOS operating systems. The supported CPU architectures include x86_64 and ARM64.

If you encounter any challenges during the installation process or have inquiries, feel free to reach out to the Lunar support team for prompt assistance and guidance at info@lunar.dev.

SSL / TLS​

You can use Transport Layer Security (TLS) for encrypting traffic between Lunar Proxy and clients. TLS is the successor to Secure Sockets Layer (SSL), which is now deprecated.

Enabling TLS​

To enable TLS for encrypting traffic between Lunar Proxy and clients, you need to provide the path to your TLS certificate file. Follow the steps below:

  1. Obtain your TLS certificate file (e.g., haproxy_cert.pem).

  2. Mount the directory containing the certificate file to the Lunar Proxy container. For example, if your certificate file is located at /organization_certs/haproxy_cert.pem, you can mount the directory /organization_certs/certs using the -v flag when running the container:

     -v /organization_certs/certs:/etc/haproxy/certs
    caution

    Make sure to replace /organization_certs/haproxy_cert.pem with the actual path to your certificate file.

  3. (Optional) Update the TLS_CERT_PATH environment variable in the Lunar Proxy container to point to the mounted certificate file if needed. The default path for the certificate is /etc/lunar-proxy/certs/haproxy_cert.pem, if your certificate is stored elsewhere, set the TLS_CERT_PATH environment variable to the appropriate path

    -e TLS_CERT_PATH="/path_to_cert/your_cert.pem"

    This ensures that Lunar Proxy can access the certificate file within the container.

  4. Save the changes and run the Lunar Proxy container for the TLS configuration to take effect.

    docker run --rm -p 443:443 -p 8000:8000 -p 8081:8081 -p 8040:8040 -e TENANT_NAME="My organization" -v $(pwd):/etc/lunar-proxy -v /organization_certs/certs:/etc/haproxy/certs --name lunar-proxy lunarapi/lunar-proxy:latest
    tip

    If you prefer LunarProxy to only listen on the secure HTTPS protocol and not on the unsecure HTTP protocol, omit the -p 8000:8000 option and keep only the -p 443:443 option when running the container. This configuration ensures that LunarProxy listens exclusively on port 443 for secure connections.

Now, Lunar Proxy will use the TLS certificate specified in TLS_CERT_PATH to encrypt traffic between the proxy and clients.

Verify TLS Support​

curl https://localhost/fact -H "x-lunar-host: catfact.ninja" -H "x-lunar-scheme: https"

Or, with wget:

wget -qO - --header="x-lunar-host: catfact.ninja" --header="x-lunar-scheme: https" https://localhost/fact"

This will make a request to Lunar Proxy on port 443, which will forward the request to the upstream server catfact.ninja on port 443, at the path /fact.

The result should look something like this:

{"fact":"Among many other diseases, cats can suffer from anorexia, senility, feline AIDS and acne.","length":89}
caution

It is important to keep your TLS certificate secure and up to date to ensure the integrity and confidentiality of your communications.

mTLS​

To enable mTLS for upstream traffic between Lunar Proxy and a secure provider, follow these steps:

  1. Provide Certificate Files: Supply the necessary certificate files as outlined in the Enabling TLS guide.
  2. Configure mTLS for the Provider: Set up the provider that requires mTLS for communication by following the instructions in this guide.

Scaling with Multiple Instances of Lunar Proxy (Lunar Pro)​

To scale Lunar Proxy, you can run multiple instances of Lunar Proxy in parallel. This setup allows you to distribute the incoming traffic across multiple instances, ensuring high availability and reliability. For more information on how to access Lunar Pro, see our pricing page.

To run Lunar Pro you need to use the lunar-proxy-pro image. To gain access to the image you will need a valid access key. Once you have the access key, install Lunar Proxy in the same way as described in the installation guide, but use the lunar-proxy-pro image instead of the lunar-proxy image.

Additionally, you will need to have a Redis instance running to store the shared state between the instances. You can use the redis image from Docker Hub to run a Redis instance.

Once you have the Redis instance running, you can start the Lunar Pro instances. You will need to provide the REDIS_URL environment variable to the Lunar Proxy Pro instances to connect to the Redis instance. The REDIS_URL should be in the format redis://<host>:<port> (or rediss://<host>:<port> if you are using TLS).

Redis with mTLS Configuration​

To configure Lunar Proxy Pro to connect to Redis using mTLS, you need to provide the necessary certificate files. Follow these steps:

  1. Obtain the CA certificate file, client certificate file, and client key file for Redis.

  2. Mount the directory containing the certificate files to the Lunar Proxy Pro container. For example, if your certificate files are located at /organization_certs/redis, you can mount the directory /organization_certs/redis using the -v flag when running the container:

     -v /organization_certs/redis:/etc/redis
    caution

    Make sure to replace /organization_certs/redis with the actual path to your certificate files.

  3. Set the REDIS_USE_CA_CERT and REDIS_USE_CLIENT_CERT environment variables to true to enable the use of the CA certificate and client certificate, respectively.

    -e REDIS_USE_CA_CERT="true" -e REDIS_USE_CLIENT_CERT="true"
    caution

    If the paths to the certificate files are different from the default paths (/etc/redis/ca.crt, /etc/redis/client.crt, /etc/redis/client.key), you need to set the REDIS_CA_CERT_PATH, REDIS_CLIENT_CERT_PATH, and REDIS_CLIENT_KEY_PATH environment variables to the appropriate paths.

     -e REDIS_CA_CERT_PATH="/path_to_cert/ca.crt" -e REDIS_CLIENT_CERT_PATH="/path_to_cert/client.crt" -e REDIS_CLIENT_KEY_PATH="/path_to_cert/client.key"

Initiate Graceful Shutdown​

When the Lunar Proxy process receives the SIGTERM signal, it initiates a graceful stop procedure. This procedure involves unbinding from listening ports while allowing existing connections to continue until they are closed. Only after the last connection is closed does the process finally exit.

Logging​

The log files for Lunar Proxy are located at /var/log/lunar-proxy. Here is a list of the specific log files and their purposes:

  • aggregation-output-plugin.log: This log file contains the logs related to the discover functionality.

  • fluent-bit.log: This log file contains the logs generated by Fluent Bit, which is a data-exporters used in Lunar Proxy.

  • lunar-engine.log: This log file contains the logs related to the Lunar Engine, which is the core component of Lunar Proxy. You can find the relevant logs in these files to troubleshoot and analyze the behavior of Lunar Proxy.

Reliability​

If Lunar Proxy stops unexpectedly, our interceptors provide failsafe mechanism, ensuring that our system maintains 100% reliability.

System Tuning​

Since Lunar Proxy is built on top of HAProxy, it is appropriate for us to consider their recommendations regarding system tuning.