• CProX
• table of contents
• about
• gettings started
  • NodeJS
    • requirements
    • install
    • run
  • Docker
    • requirements
    • run
• configuration
  • cli
  • environment variables
• rules
• rule order
  • set rules in docker
  • set rules for cli tool
  • rule types
    • redirect
    • static
    • proxy
    • other examples
  • rule variables
    • variable mapping
    • wildcards in variables
    • use variables
    • examples
• examples
  • static example
  • big example
• Load balancing
  • Define targets
  • Redirect
  • Proxy
• npm scripts
  • use
  • base scripts
  • watch mode
• contribution

| Docker Hub | GitHub |
CProX is easy customizable static, redirct and proxy server.

docker pull majo418/cprox:latest

Checkout the test.sh and the start.sh scripts to understand what you need to think about and how to start the server.

• node v16
• Linus distrubotion

npm i -g cprox

Run as redirect server:

cprox *=REDIRECT:https://start.duckduckgo.com

Run as static file server:

cprox *=STATIC:/var/www/html

Run as proxy server:

cprox *=PROXY:http://127.0.0.1:8080

Help:

cprox -h

• docker cli
• Linus distrubotion

docker run -it --rm -p 80:80 -p 443:443 majo418/cprox *=REDIRECT:https://start.duckduckgo.com

Help:

docker run -it --rm majo418/cprox -h

You configure the server with variables and rules. That config is adjustable via environment variables or the cli.

This is the output of the cprox -h cli command. You can overwrite the default environment varaible values by using the flags. The none flag arugments are the cprox rules.

# CPROX #

Usage: cprox [OPTIONS] [ARGUMENTS]

CProX is a easy to configure redirect, proxy and static webserver.

Options:
  -v, --verbose                                  Show basic flag adn target informations.
  -p, --http-port [number]                       Set the http port (default: 80 but disabled if any port is set)
  -s, --https-port [number]                      Set the https port (default: 443 but disabled if any port is set)
  -t, --trust-all-certs                          Trust all certificates on proxy.
  -b, --bind-host-address [string]               Set the host where the server pind the ports.
      --disable-self-singed                      Disable generating self singed certificates if not exist.
  -d, --self-singed-domain [string]              Set the domain name for self singed certificates.
      --dns-server-address [string]              Add a dns address to the existing dns addresses.
      --cert-path [string]                       Define the path for the certificates.
      --cert-name [string]                       Define the name for the certificates cert file.
      --key-name [string]                        Define the name for the certificates key file.
      --ca-name [string]                         Define the name for the certificate ca file.
  -r, --rule [string]                            CProX rules
      --request-timeout [number | string]        Define the maximum time in miliseconds (or as millisecond calucaltion) for the request content.
      --connection-timeout [number | string]     Define the maximum time in miliseconds (or as millisecond calucaltion) for a open conneciton.
      --proxy-reaction-timeout [number | string] Define the maximum time in miliseconds (or as millisecond calucaltion) that the proxy target has to respond.
      --proxy-verify-certificate                 Proxy verify target certificates
      --proxy-follow-redirects                   Proxy follow redirects
  -h, --help                                     Shows this help output

Details:
You can use CProX as webserver. It can proxy, redirect and service static content on requests.

! CProX | by majo418 | supported by CoreUnit.NET !

The environment variables configure the webserver settings like http port, https port, certificat path, certificat name and bound host address. The default values can be overwriten by the cli tool flags. You can find the adjustable environment variables here: https://github.com/majo418/cprox/blob/main/src/env/env.ts

A rule is a key value pair as string that can be set over the environment variables or via the cli process arguments.

Its containers the origin target, rule type and rule target:
<origin>=<type>:<target>

CProX automatically sort the rules by this order:

• host parts ("." as seperator) if equal
• host part size if equal
• rule insert order (environemtn varaibles first)

Just pass the rules as arguments to the process:

docker run -p 80:80 majo418/cprox <rule1> <rule2> <rule3>

Or via environment variables via RULE_<n> where <n> is the rule number:

docker run \
    -p 80:80 \
    -e "RULE_1=<rule1>" \ 
    -e "RULE_2=<rule2>" \
    -e "RULE_3=<rule3>" \
    majo418/cprox

Just pass the rules as arguments to the process:

cprox <rule1> <rule2> <rule3>

Or via environment variables via RULE_<n> where <n> is the rule number:

export RULE_1="<rule1>"
export RULE_1="<rule2>"
export RULE_1="<rule3>"
cprox

The following rule all requests to the host example.com on the path /test to https://youtube.com:

example.com/test=REDIRECT:https://youtube.com

The following rule redirects all requests on the path /redirect to https://hub.docker.com:

*/redirect=REDIRECT:https://hub.docker.com

The following rule provides the static content of the /var/www/html folder as website if example.com is the host address:

example.com=STATIC:/var/www/html

The following rule forward localhost to http://localhost:8080:

localhost=PROXY:localhost:8080

The following rule forward auth.coreunit.net to a keycloak docker container in the same network that not publish a port:

auth.coreunit.net=PROXY:keycloak:8080

• localhost/youtube=REDIRECT:https://youtube.com/
• *.localhost=REDIRECT:https://duckduckgo.com/?t=vivaldi&ia=web&q={-2}
• localhost=STATIC:./public

The rules support variables.
A variables is always a number that is never 0.
Numbers greater than 0 represent a part of the requested path splitted by /.
Numbers lesser than 0 represent a part of the requested domain splitted by ..

If the requested address is test.coreunit.net/test/test2/test3 you can get the following variables:

• {-3} = "test"
• {-2} = "coreunit"
• {-1} = "net"
• {1} = "test"
• {2} = "test2"
• {3} = "test3"

That also works with wildcards! If the requested address is *.test.coreunit.net you can get the following variables:

• {-4} =
• {-3} = "test"
• {-2} = "coreunit"
• {-1} = "net"

You can use the variables in the value part of the rules like that:
*.localhost=REDIRECT:https://duckduckgo.com/?q={-2}
If you request some_test.localhost you will get redirected to https://duckduckgo.com/?q=some_test.

Same with paths:
localhost/*=REDIRECT:https://duckduckgo.com/?q={1}
If you request localhost/some_value you will get redirected to https://duckduckgo.com/?q=some_value.

That also works with proxy and static rules!
Here is a example with docker containers:
*.con.localhost=PROXY:c_{-3}:8080
If you request mynginx.con.localhost the request get proxied to c_mynginx:8080.

Here some rule examples:

 - "localhost/youtube=REDIRECT:https://youtube.com/"
 - "*.localhost=REDIRECT:https://duckduckgo.com/?q={-2}"
 - "localhost=STATIC:./public"
 - "localhost/test=STATIC:./dist"
 - "*.cprox.coreunit.net=PROXY:cprox_{-4}:8080"
 - "*.test.i.coreunit.net=PROXY:test_{-4}"
 - "coreunit.net=STATIC:/var/www/main"
 - "auth.coreunit.net=PROXY:keycloak_container:8080"
 - "majo.coreunit.net=REDIRECT:https://github.com/majo418"
 - "sysdev.coreunit.net=REDIRECT:https://github.com/sysdev"
 - "cprox.coreunit.net=STATIC:/var/www/cprox"
 - "i.coreunit.net=STATIC:/var/www/intern"
 - "i.coreunit.net/certs=STATIC:/home/netde/certs"
 - "discord.coreunit.net=REDIRECT:https://discord.gg/pwHNaHRa9W"
 - "teamspeak.coreunit.net=REDIRECT:ts3server://coreunit.net"
 - "github.coreunit.net=REDIRECT:https://github.com/coreunitnet"
 - "/.well-known=STATIC:/home/netde/certs/.well-known"
 - "/test=STATIC:/home/netde/certs/.well-known"
 - "/qweqwesdsdddsdsdsdsde=STATIC:/home/netde/certs/.well-known"

docker run -it --rm \
    --name cprox \
    -e "RULE_1=stat.coreunit.net=STATIC:/var/www/html" \
    -v /var/www/html:/var/www/html \
    -p 8443:443 \
    majo418/cprox

docker run -it --rm \
    --name cprox \
    -e "VERBOSE=true" \
    -e "PRODUCTION=true" \
    -e "RULE_1=static.test.net=STATIC:/var/www/html" \
    -e "RULE_2=redirect.test.net=REDIRECT:http://target.test2.net" \
    -e "RULE_1=proxy.test.net=PROXY:http://my.target.test2.net:8080" \
    -e "SELF_SINGED_DOMAIN=test.net" \ # -e "SELF_SINGED_IF_NEEDED=false" to disable self singed certs
    -e "CERT_PATH=/app/certs/pub.pem" \
    -e "KEY_PATH=/app/certs/key.pem" \
    -e "CA_PATH=/app/certs/chain.pem" \
    -v "/var/www/html:/var/www/html" \
    -v "/home/certs:/app/certs" \
    -p 443:443 \
    -p 80:80 \
    majo418/cprox

A feature of CProX is load balancing. This is available for REDIRECT and PROXY rules.

You define multiple load balancer targets using commas.
Example:

*=REDIRECT:https://start.duckduckgo.com,https://startpage.com,https://google.de

If you define multiple targets in a REDIRECT rule, CProx will use the available targets alternately.
Example:

*=REDIRECT:https://start.duckduckgo.com,https://startpage.com,https://google.de

Response Location header example:

1. Location: https://start.duckduckgo.com
2. Location: https://startpage.com
3. Location: https://google.de
4. Location: https://start.duckduckgo.com

If you define multiple targets in a PROXY rule, CProx will use the available targets alternately. But, if there are still open proxy connections, CProX will use the least used target for new incomming request. Example:

*=PROXY:http://127.0.0.1:8080,http://127.0.0.1:8081,http://127.0.0.1:8082

Request proxy target example:

1. Open: http://127.0.0.1:8080
2. Open: http://127.0.0.1:8081
3. Open: http://127.0.0.1:8082
4. Open: http://127.0.0.1:8080
5. Open: http://127.0.0.1:8081
6. Close: http://127.0.0.1:8081
7. Close: http://127.0.0.1:8081
8. Open: http://127.0.0.1:8081
9. Open: http://127.0.0.1:8081

The npm scripts are made for linux but can also work on mac and windows.

You can run npm scripts in the project folder like this:

npm run <scriptname>

Here is an example:

npm run test

You can find all npm scripts in the package.json file. This is a list of the most important npm scripts:

• test // test the app
• build // build the app
• exec // run the app
• start // build and run the app

Like this example you can run all npm scripts in watch mode:

npm run start:watch

• 1. fork the project
• 2. implement your idea
• 3. create a pull/merge request

// please create seperated forks for different kind of featues/ideas/structure changes/implementations

cya ;3
by majo418