Skip to content

Latest commit

 

History

History
124 lines (84 loc) · 4.01 KB

CONTRIBUTING.md

File metadata and controls

124 lines (84 loc) · 4.01 KB
Raw

Git

To contribute to KleckRelay you will need to set up signed commits. We will reject any pull request that contains unverified commits.

To contribute to KleckRelay, please follow the following steps:

  1. Fork the repository
  2. Create a new branch following kebab-case (e.g. new-feature)
  3. Make your changes
  4. Commit your changes (make sure to sign your commits!)
  5. Push your changes to your fork
  6. Create a pull request
  7. Explain what your pull request does and why it is necessary
  8. If your pull request is accepted, it will be merged into the main branch 🥳

Contributing

To test KleckRelay locally, we strongly recommend to run the following services as follows:

  1. PostgreSQL -> Docker container
  2. Main Worker -> On your machine
  3. Email Handler -> On your machine

This setup makes it easier to debug the application as you will not need to rebuild the whole docker images each time you change something.

If you prefer simplicity however, you can also simply rebuild the docker image each time you change something, but this will be slower. The command for this is docker-compose up --force-recreate --build.

Here's what to do based on what you want to contribute to

Main Worker

To enable debug mode (which will allow logging as logs are disabled by default), edit the following environmental variable:

  1. IS_DEBUG=true

Setting up the database

For the main Python worker you will need to run the database either by setting up a manual PostgreSQL server or by running the database service inside the docker-compose.yaml file.

The default database connection string should work out of the box using this setup, otherwise edit the environmental variable DB_URI.

Setting up emails

To receive emails locally, edit the following environmental variable:

  1. DEBUG_MAILS=true

Setting up a custom domain

To set up a custom domain, please see how to set up a custom local domain.

Email Handler

You only need to run the Email Handler when you want to change how incoming emails will be forwarded

To enable debug mode (which will allow logging as logs are disabled by default), edit the following environmental variable:

Sending emails

To test the email handler locally, make sure you have set the following environment variables:

  1. POSTFIX_HOST=127.0.0.1
  2. POSTFIX_PORT=1025
  3. POSTFIX_USE_TLS=False

After that, you can send mails to the handler using swaks, here are some example commands:

Send a mail from outside mail to local mail

swaks --to m1fNY7@mail.app.krl --from outside@example.com --server 127.0.0.1:20381 --header 'Subject: Hello'

Send a mail with trackers in it

swaks --to m1fNY7@mail.app.krl --from outside@example.com --server 127.0.0.1:20381 --header 'Subject: Hello'  --body explorative_tests/image_tracker_url.html

See explorative_tests for more test files.

How to set up a custom local domain

In order to access your localhost using a custom domain (for example app.krl) you can do the following.

When you set up a custom domain, make sure to change these environmental variables (assuming you use app.krl and mail.app.krl):

APP_DOMAIN=app.krl
API_DOMAIN=app.krl
MAIL_DOMAIN=mail.app.krl

Unix (Linux, MacOS)

  1. Edit /etc/hosts (e.g. vim /etc/hosts, nano /etc/hosts)
  2. Navigate to the line that starts with 127.0.0.1 (this will probably be one of the first lines)
  3. Append your domains
    1. For KleckRelay we want to add app.krl to access the web interface,
    2. mail.app.krl for the emails and
    3. api.app.krl for the server
  4. Save the file
  5. You can now access localhost using app.krl!
    1. Keep in mind that you need to prefix this domain with a protocol, as the browser otherwise will do a search query (e.g. instead of typing app.krl, type in http://app.krl)
  6. To access the web interface in debug mode, go to http://app.krl:5173