spatz

Reverse-Proxy in the cloud

Getting Started

These instructions will give you a copy of the project up and running on your local machine for development and testing purposes.

Prerequisites

Requirements for the software and other tools to build, test and push

• Git
• Docker

Supported IDEs

You can use the IDE of your choice to continue developing the project. However, the following IDEs are recommended and officially supported:

• VSCodeium
• Visual Studio Code

Secret Management

Sensitive data is stored in a .env file. An empty example of the structure can be found in .env.example

Development

This repository is a full functional docker compose application stack. Therefore, you can use the terminal to deploy a development instance on your local machine.

docker-compose --profile all up -d

Deployment Preperation

For the first deployment, some preconditions have to be met:

• Make sure the public network exists in docker
• Make sure the $PATH directory on the server exists

Deployment

The deployment itself is a multistage plan:

1. Gracefull shutdown of the stack
2. Update the files on the server
3. Generate CrowdSec API key
4. Start the core services
5. Start the complementary services

To keep the documentation server agnostic the following placeholders are used The $USER variable holds the username of the user on the server.
The $SERVER variable holds the IP-address or the domain of the server.
The $PATH variable holds the absolut path to the application folder on the server.

These placeholders can be set for the current session with

export USER=user
export SERVER=192.168.x.x
export PATH=/path/to/project

Graecefull shutdown

To prevent race conditions or corrupted files, the complete stack should be stoped

ssh $USER@$SERVER "docker compose -f $PATH/docker-compose.yaml --profile all down"

Update the files

Now the updated files can be copied to the server

scp .env $USER@$SERVER:/$PATH/
scp docker-compose.yaml $USER@$SERVER:/$PATH/
scp -r config $USER@$SERVER:/$PATH/
ssh $USER@$SERVER "find $PATH/config -type d -exec chmod 755 {} \;"
ssh $USER@$SERVER "find $PATH/config -type f -exec chmod 644 {} \;"
ssh $USER@$SERVER "find $PATH/config/letsencrypt -type f -exec chmod 600 {} \;"
scp -r crowdsec $USER@$SERVER:/$PATH/
ssh $USER@$SERVER "find $PATH/crowdsec -type d -exec chmod 755 {} \;"
ssh $USER@$SERVER "find $PATH/crowdsec -type f -exec chmod 644 {} \;"

Generating CrowdSec API key

The traefik service depends on the crowdsec security engine. Therefore, traefik needs an API key to connect to this security engine. If this API key is not known yet, a new API key must be generated.

ssh $USER@$SERVER "docker compose up crowdsec --no-deps -d"
ssh $USER@$SERVER "docker exec crowdsec cscli bouncers add traefik-bouncer"
ssh $USER@$SERVER "docker compose down crowdsec"

Update the CROWDSEC_LAPI_KEY variable in the .env file with the API key displayed. If you updated the file localy, do not forget to sync the changes to the server!

Starting the core servies

The core services must be running and functional befor loading the other services. The complementary services depend on the core services in a manner witch is not representable in Docker. For example could a complementary service beeing registered by a core service within a UI.

ssh $USER@$SERVER "docker compose --profile stage1 up -d"

Start the complementary services

Now register a new newt site in pangolin and copy the generated id and secret to the .env file to the NEWT_ID and NEWT_SECRET variable.

ssh $USER@$SERVER "docker compose --profile all up -d"

Troubleshooting

Sometimes things go wrong. Here are some tips, how to troubleshoot

Self-Banning

When updating the complete stack it is possible you get self-banned, since the monitoring stack on the homeserver runs on the same IP than your computer. When upgrading the stack tries to reconnect to this server and thereby runs in the bruteforce protection of crowdsec.

ssh $USER@$SERVER "sudo docker exec crowdsec cscli decisions list"

If your local IP is in these decisions, unban yourself with the following command

ssh $USER@$SERVER "sudo docker exec crowdsec cscli decisions delete --ip $IP"

Authors

• Lukas Gysin - Main Contributor & Project Owner

License

This project is licensed under the MIT License

Acknowledgments

• Billie Thompson - Provided README Template
• Contributor Covenant - Provided CODE_OF_CONDUCT Template