From 2c460973301b79cd1298808233a30e9103f13648 Mon Sep 17 00:00:00 2001 From: Son Date: Sat, 6 Mar 2021 16:28:15 +0100 Subject: [PATCH] improve contributing.md, comment all optional options in example.env --- CONTRIBUTING.md | 26 ++++++++++--------- example.env | 69 +++++++++++++++++++++++-------------------------- 2 files changed, 47 insertions(+), 48 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2e152367..742fff40 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,6 @@ -All work on SimpleLogin happens directly on GitHub. +Thanks for taking the time to contribute! 🎉👍 + +The project uses Flask and requires Python3.7+. ### Run code locally @@ -43,12 +45,7 @@ To run the code locally, please create a local setting file based on `example.en cp example.env .env ``` -Make sure to uncomment the `RESET_DB=true` to create the database locally. - -Feel free to custom your `.env` file, it would be your default setting when developing locally. This file is ignored by git. - -You don't need all the parameters, for example, if you don't update images to s3, then -`BUCKET`, `AWS_ACCESS_KEY_ID` can be empty or if you don't use login with Github locally, `GITHUB_CLIENT_ID` doesn't have to be filled. The `example.env` file contains minimal requirement so that if you run: +To run the server: ``` python3 server.py @@ -60,6 +57,8 @@ then open http://localhost:7777, you should be able to login with the following john@wick.com / password ``` +You might need to change the `.env` file for developing certain features. This file is ignored by git. + ### Database migration The database migration is handled by `alembic` @@ -106,11 +105,11 @@ black . [swaks](http://www.jetmore.org/john/code/swaks/) is used for sending test emails to the `email_handler`. -[mailcatcher](https://github.com/sj26/mailcatcher) is used to receive forwarded emails. +[mailcatcher](https://github.com/sj26/mailcatcher) or [MailHog](https://github.com/mailhog/MailHog) can be used as a MTA to receive emails. -There are several steps to set up the email handler +Here's how set up the email handler: -1) run mailcatcher +1) run mailcatcher or MailHog ```bash mailcatcher @@ -119,7 +118,10 @@ mailcatcher 2) Make sure to set the following variables in the `.env` file ``` -NOT_SEND_EMAIL=true +# comment out this variable +# NOT_SEND_EMAIL=true + +# So the emails will be sent to mailcatcher/MailHog POSTFIX_SERVER=localhost POSTFIX_PORT=1025 ``` @@ -133,7 +135,7 @@ python email_handler.py 4) Send a test email ```bash -swaks --to e1@d1.localhost --from hey@google.com --server 127.0.0.1:20381 +swaks --to e1@sl.local --from hey@google.com --server 127.0.0.1:20381 ``` Now open http://localhost:1080/, you should see the test email. \ No newline at end of file diff --git a/example.env b/example.env index f7a8365c..971313e2 100644 --- a/example.env +++ b/example.env @@ -1,3 +1,7 @@ +# This file contains all available options in SimpleLogin. +# Some are optional and are commented out by default. +# Some are only relevant for our SaaS version, for example for payment integration, analytics, etc. + # Server url URL=http://localhost:7777 @@ -11,24 +15,23 @@ URL=http://localhost:7777 # apply colored log to facilitate local development # COLOR_LOG=true -# <<< Email related settings >>> # Only print email content, not sending it, for local development -# NOT_SEND_EMAIL=true +NOT_SEND_EMAIL=true # domain used to create alias EMAIL_DOMAIN=sl.local # Allow SimpleLogin to enforce SPF by using the extra headers from postfix -ENFORCE_SPF=true +# ENFORCE_SPF=true # other domains that can be used to create aliases, in addition to EMAIL_DOMAIN -OTHER_ALIAS_DOMAINS=["domain1.com", "domain2.com"] +# OTHER_ALIAS_DOMAINS=["domain1.com", "domain2.com"] # domains that can be used to create aliases. If set, override OTHER_ALIAS_DOMAINS -ALIAS_DOMAINS=["domain1.com", "domain2.com"] +# ALIAS_DOMAINS=["domain1.com", "domain2.com"] # (optional) domains that are only available to premium accounts -PREMIUM_ALIAS_DOMAINS=["premium.com"] +# PREMIUM_ALIAS_DOMAINS=["premium.com"] # the alias domain used when creating the first alias for user, default to EMAIL_DOMAIN if not set # FIRST_ALIAS_DOMAIN = another-domain.com @@ -42,12 +45,12 @@ SUPPORT_NAME=Son from SimpleLogin # BOUNCE_PREFIX = "bounces+" # BOUNCE_SUFFIX = "+@sl.local" - # to receive general stats. # ADMIN_EMAIL=admin@sl.local # Max number emails user can generate for free plan -MAX_NB_EMAIL_FREE_PLAN=5 +# Set to 5 by default +# MAX_NB_EMAIL_FREE_PLAN=5 # Close registration. Avoid people accidentally creating new account on a self-hosted SimpleLogin # DISABLE_REGISTRATION=1 @@ -71,37 +74,31 @@ DKIM_PRIVATE_KEY_PATH=local_data/dkim.key # the DKIM public key used to setup custom domain DKIM DKIM_PUBLIC_KEY_PATH=local_data/dkim.pub.key -# <<< END Email related settings >>> -# <<< Database >>> -# delete and recreate sqlite database, for local development -# RESET_DB=true +# delete and recreate the sqlite database, for local development +RESET_DB=true # DB Connection # Local SQLite database DB_URI=sqlite:///db.sqlite # Postgres # DB_URI=postgresql://myuser:mypassword@sl-db:5432/simplelogin -# <<< END Database >>> -# Flask FLASK_SECRET=secret -# <<< AWS >>> -BUCKET=to_fill -AWS_ACCESS_KEY_ID=to_fill -AWS_SECRET_ACCESS_KEY=to_fill -AWS_REGION=to_fill - -# <<< END AWS >>> +# AWS params +# BUCKET=to_fill +# AWS_ACCESS_KEY_ID=to_fill +# AWS_SECRET_ACCESS_KEY=to_fill +# AWS_REGION=to_fill # Paddle -PADDLE_VENDOR_ID=123 -PADDLE_MONTHLY_PRODUCT_ID=123 -PADDLE_YEARLY_PRODUCT_ID=123 -PADDLE_PUBLIC_KEY_PATH=local_data/paddle.key.pub -PADDLE_AUTH_CODE=123 +# PADDLE_VENDOR_ID=123 +# PADDLE_MONTHLY_PRODUCT_ID=123 +# PADDLE_YEARLY_PRODUCT_ID=123 +# PADDLE_PUBLIC_KEY_PATH=local_data/paddle.key.pub +# PADDLE_AUTH_CODE=123 # OpenId key OPENID_PRIVATE_KEY_PATH=local_data/jwtRS256.key @@ -110,17 +107,17 @@ OPENID_PUBLIC_KEY_PATH=local_data/jwtRS256.key.pub # Words to generate random email alias WORDS_FILE_PATH=local_data/words.txt -# Github -GITHUB_CLIENT_ID=to_fill -GITHUB_CLIENT_SECRET=to_fill +# Login with Github +# GITHUB_CLIENT_ID=to_fill +# GITHUB_CLIENT_SECRET=to_fill -# Google -GOOGLE_CLIENT_ID=to_fill -GOOGLE_CLIENT_SECRET=to_fill +# Login with Google +# GOOGLE_CLIENT_ID=to_fill +# GOOGLE_CLIENT_SECRET=to_fill -# Facebook -FACEBOOK_CLIENT_ID=to_fill -FACEBOOK_CLIENT_SECRET=to_fill +# Login with Facebook +# FACEBOOK_CLIENT_ID=to_fill +# FACEBOOK_CLIENT_SECRET=to_fill # Flask profiler # FLASK_PROFILER_PATH=/tmp/flask-profiler.sql @@ -131,7 +128,7 @@ FACEBOOK_CLIENT_SECRET=to_fill # By default, files are uploaded to s3 # Set this variable to use the local "static/upload/" directory instead -# LOCAL_FILE_UPLOAD=true +LOCAL_FILE_UPLOAD=true # The landing page # LANDING_PAGE_URL=https://simplelogin.io