YAML

Proksi can be configured using a proksi.yaml file that controls most of the functions:

Property	Description	Default
service_name	Name of the service. It's used for logging.	"proksi"
worker_threads	Number of (real) threads the HTTPs service will use.	4
lets_encrypt	--	--
lets_encrypt.enabled	Enables issuing certificates from Let's Encrypt	true
lets_encrypt.email	The email to be used when asking for certificates	""
lets_encrypt.staging	Use the staging endpoint to generate certificates. Mostly useful for local testing. Change it to true to enable the production certificates.	true
logging	--	--
logging.level	The level of logs saved or printed to STDOUT.	INFO
logging.access_logs_enabled	Enables response/request logging (includes user-agent, host, duration etc)	true
logging.error_logs_enabled	If the logs should include errors from Pingora	false
paths	--	--
paths.lets_encrypt	Path to store certificates, challenges etc	"/etc/proksi/lets_encrypt"
routes	--	--
routes[*].host	The host name that a list of upstreams will receive requests for
routes[*].path_prefix	Will match host+path on every request ensuring that only requests where the path starts with the value defined here are matched.
routes[*].upstreams	--	--
routes[*].upstreams[*].ip	The IP of your server, container, or even an external IP you want to point requests to.
routes[*].upstreams[*].port	The PORT of your server, container or external service where we should connect to.
routes[*].upstreams[*].network	The network name for Proksi to use when connecting with internal services or containers

Example file

Below you can find a file with the current defaults and

# Description: Example configuration file for Proksi
#
# Proksi is a reverse proxy server that can be used to route incoming requests 
# to different upstream servers based on the request's host, path, headers, and 
# other attributes.
#
# This configuration file specifies the following settings:
#
#
# ------------------------------------------------------------------
# The name of the service is "proksi".
# This will show in logs and it's mostly used for log filtering if needed
service_name: "proksi"

# Number of threads that the HTTPS service will use to handle incoming requests.
# This can be adjusted based on the number of CPU cores available on the server.
# The default value is 1.
#
# Note: Increasing the number of threads can improve the performance of the server, 
# but it can also increase the memory usage.
#
# Note 2: This only affect the HTTPS service, the HTTP service
# (and other background services) is single threaded.
worker_threads: 4

# The configuration for the Let's Encrypt integration.
lets_encrypt:

  # Whether the Let's Encrypt integration is enabled
  # (the background service will run and issue certificates for your routes).
  enabled: true

  # The email address to use for Let's Encrypt notifications and account registration.
  # Important: Make sure to replace this with your own email address.
  # any "@example.com" is invalid and will not work.
  email: "[e-mail]"

  # The staging flag is used to test the Let's Encrypt integration without hitting the rate limits.
  # When set to <true>, the integration will use the Let's Encrypt staging environment.
  # --
  # When set to <false>, the integration will use the Let's Encrypt production environment
  # and certificates will be publicly trusted for 90 days.
  staging: true

# The logging configuration for the server.
logging:
  # The log level for the server (can be "DEBUG", "INFO", "WARN", "ERROR").
  level: "INFO"

  # Whether access logs are enabled.
  # When set to <true>, the server will log information about incoming requests.
  # This information includes the request method, path, status code, response time and more.
  access_logs_enabled: true

  # Whether error logs are enabled.
  error_logs_enabled: false

# The paths for the TLS certificates, challenges, orders, and account credentials.
# You can override any, these are the current defaults.
paths:

  # The path where the TLS certificates will be stored.
  # If the path doesn't exist, it will be created if the binary has the right permissions.
  lets_encrypt: "/etc/proksi/certificates"


# The list of routes that the server will use to route incoming requests
# to different upstream servers.
# Each route is an item in the list and it has the following attributes:
routes:

  # The host attribute specifies the hostname that the route will match.
  # This is normally the domain, subdomain that you want to route to a particular server/ip.
  # This can be a domain name or an IP address. For IP address, no certificate will be issued.
  # The host attribute is required.
  - host: "example.com"

    # The path_prefix attribute specifies the path prefix that the route will match.
    path_prefix: "/api"

    # The headers attribute specifies the headers that will
    # be added or removed at the end of the response
    # --
    # In the near future you will be able to modify the headers
    # of the request send to the upstream server
    headers:
      # Adds the given headers to the dowstream (client) response
      add:
        - name: "X-Forwarded-For"
          value: "<value>"
        - name: "X-Api-Version"
          value: "1.0"
      # Removes the given headers from the dowstream (client) response
      remove:
        - name: "Server"
    # The upstreams attribute specifies the list of upstream servers that the route will use.
    # These are load balanced and the server will try to connect to the first one in the list.
    # If the connection fails, it will try the next one.
    # --
    # Health checks run in the background to ensure you have a healthy connection always.
    upstreams:
      # The IP address of the upstream server
      # (can be any IP address, as long as Proksi can access it).
      - ip: "10.1.2.24/24"
        # The port of the upstream server (can be any port).
        port: 3000

        # The network attribute specifies the network that the upstream server is part of.
        # This is mostly important for Docker containers, but it can be used for other purposes.
        network: "public"
      - ip: "10.1.2.23/24"
        port: 3000
        network: "shared"