So, you want to help with the development of TiBillet. Thank you! Open-source thrives thanks to people like you 🙏
First, if you don't have a specific task in mind already, check out the open issues on the official Github repositories.
It's the easiest way to figure out what problem needs fixing or what feature is being requested.
-What you need is probably in the pinned repositories. If you are unsure of the role of Fedow, Laboutik or Lespass, check out the basics on the three TiBillet engines.
TODO: link to engines and their roles in the doc (a very basic page in intro probably)
What you need is probably in the pinned repositories. If you are unsure of the role of Fedow, LaBoutik or Lespass, check out the basics on the three TiBillet engines.
TODO: link to engines and their roles in the doc (a very basic page in intro probably)
When you work with Git forges like Github, there are ways in which you can make your contributions easier to handle:
The legacy way of generating the necessary configuration keys is to pull the production Fedow docker image and run poetry inside of it.
For each engine, we will need:
FERNET_KEY field and possibly, passwords)SECRET_KEY field)You can generate 30 of each in your terminal by running:
docker run --rm tibillet/fedow poetry run python3 -c "from cryptography.fernet import Fernet; print('\n'.join([Fernet.generate_key().decode('utf-8') for i in range(0,30)]))"
docker run --rm tibillet/fedow poetry run python3 -c "from django.core.management.utils import get_random_secret_key; print('\n'.join([get_random_secret_key() for i in range(0,30)]))"
The first line will take some time as it need to pull the entire Docker image. Keep the keys somewhere, we're gonna need them to setup the engines.
-We're also going to need a Stripe test key for the STRIPE_KEY_TEST field. Stripe is the payment solution that is currently taking care of the cashing in. You can obtain a key by creating a free account, then by going to Test mode -> API test key. Alternatively you can ask the team.
Start by cloning the repositories:
git clone git@github.com:TiBillet/Fedow.git
git clone git@github.com:TiBillet/Lespass.git
git clone git@github.com:TiBillet/LaBoutik.git
From here, we need to write a bit of configuration. It will be better streamlined in the future, so bear with us 😋
Each engine needs its own .env file, which you can base on the env_example files you cloned.
Each environment variable must be readable from the .env file. No line deletion! Some of them can however stay empty (nullable).
cp Fedow/env_example Fedow/.env
SECRET_KEY='' # add a Django secret key here
FERNET_KEY='' # same with one of the Fernet key you previously generated
DOMAIN='fedow.tibillet.localhost' # default local domain, referenced in docker-compose.yml
### FOR TEST AND DEBUG ###
DEBUG=1
TEST=1
STRIPE_TEST=1
STRIPE_KEY_TEST='' # ask the core team! for obvious reasons, we don't freely distribute Stripe keys 😉
STRIPE_ENDPOINT_SECRET_TEST='' # not required in development
You can follow the same process for Lespass, even if the environment setup is different.
+| Name | Target environment | Nullable | Default value | Notes |
|---|---|---|---|---|
SECRET_KEY | All | No | One of the previously generated Django secret key | |
FERNET_KEY | All | No | One of the previously generated Fernet key | |
STRIPE_KEY | Production | Yes | Your Stripe API key | |
DOMAIN | All | No | fedow.tibillet.localhost | Change to you domain and subdomain for production mode |
STRIPE_KEY_TEST | Development, Testing | Yes | Your Stripe API test key | |
STRIPE_TEST | Development, Testing | No | 0 | Set to 1 if STRIPE_KEY_TEST is filled |
STRIPE_ENDPOINT_SECRET_TEST | Development, Testing | Yes | No idea | |
DEBUG | Development | No | 0 | Set to 1 for development |
TEST | Testing | No | 0 | Set to 1 for testing |
cp Lespass/env_example Lespass/.env
DJANGO_SECRET='' # Django secret key, different from the Fedow env
FERNET_KEY='' # same with a different Fernet
DEBUG=1
TEST=1
STRIPE_TEST=1
STRIPE_KEY_TEST='' # same as in Fedow env
# Database
POSTGRES_HOST='lespass_postgres' # referenced in docker-compose.yml
POSTGRES_USER='lespass_postgres_user'
POSTGRES_PASSWORD='' # you can add a second Fernet key here (or another strong password)
POSTGRES_DB='lespass'
TIME_ZONE='Europe/Paris' # TZ timezone identifier
PUBLIC='TiBillet Coop.' # instance name
FEDOW_DOMAIN='fedow.tibillet.localhost' # federation engine domain
DOMAIN='tibillet.localhost' # for the wildcard: without subdomain ! ex : tibillet.coop, not lespass.tibillet.coop
SUB='demo' # instance referenced in docker-compose.yml as demo.tibillet.localhost
META='agenda' # the federated agenda for all events on all tenants. the default setup is accessible as agenda.tibillet.coop
ADMIN_EMAIL='' # required but will not be used in dev to send email
# not required in dev
EMAIL_HOST=''
EMAIL_PORT=''
EMAIL_HOST_USER=''
EMAIL_HOST_PASSWORD=''
# change only if needed
CELERY_BROKER='redis://redis:6379/0'
CELERY_BACKEND='redis://redis:6379/0'
Lastly, we configure Laboutik in the same way:
-cp Laboutik/env_example Laboutik/.env
DJANGO_SECRET='' # yet another unique Django secret key
FERNET_KEY='' # unique Fernet key
DEBUG=1
TEST=1
DEMO=1
POSTGRES_USER='laboutik_user'
POSTGRES_PASSWORD='' # again, you can use a unique Fernet for this or a strong password of your choice
POSTGRES_DB='laboutik'
DOMAIN='cashless.tibillet.localhost' # default, referenced in docker-compose.yml
# laboutik requires Fedow and a Lespass instance (tenant)
FEDOW_URL='https://fedow.tibillet.localhost/'
LESPASS_TENANT_URL='https://demo.tibillet.localhost/'
# name of your cashless asset (virtual currency)
MAIN_ASSET_NAME='TestCoin'
# admin email, required but not in use in dev, use the same as for lespass
ADMIN_EMAIL=''
# still not required in dev
EMAIL_HOST=""
EMAIL_PORT=""
EMAIL_HOST_USER=""
EMAIL_HOST_PASSWORD=""
TIME_ZONE='Europe/Paris'
LANGUAGE_CODE='fr'
########## FOR SAVE CRON TASK ##########
# can be empty if you don't backup
BORG_PASSPHRASE=""
########## FOR TEST AND DEBUG ONLY ##########
# Sentry Debug for django backend
SENTRY_DNS=""
# Sentry Debug for js frontend
SENTRY_FRONT_DNS=""
SENTRY_FRONT_ASSET=""
###!!!!!! Don't push to production with debug, test or demo !!!!!!###
DEMO_TAGID_CM=''
DEMO_TAGID_CLIENT1=''
DEMO_TAGID_CLIENT2=''
| Name | Target environment | Nullable | Default value | Notes |
|---|---|---|---|---|
SECRET_KEY | All | No | One of the previously generated Django secret key | |
FERNET_KEY | All | No | One of the previously generated Fernet key | |
STRIPE_KEY | Production | Yes | Your Stripe API key | |
DOMAIN | All | No | tibillet.localhost | Change to your domain for production mode |
SUB | All | No | lespass | Instance subdomain, change for production mode as necessary |
META | All | No | agenda | Federated calendar subdomain, change for production mode as necessary |
FEDOW_DOMAIN | All | No | fedow.tibillet.localhost | Domain and subdomain of the Fedow engine |
PUBLIC | All | No | TiBillet Coop. | Main instance name |
TIME_ZONE | All | No | Europe/Paris | TZ time zone of the instance |
ADMIN_EMAIL | All | No | Admin email (for the first admin) | |
POSTGRES_DB | All | No | lespass | Change for production mode if necessary |
POSTGRES_USER | All | No | lespass_postgres | Change for production mode |
POSTGRES_PASSWORD | All | No | Strong password (one of the Fernet keys for example) | |
EMAIL_HOST, EMAIL_PORT, EMAIL_HOST_USER, EMAIL_HOST_PASSWORD | All | Yes | Email server, required to confirm user registrations for example | |
STRIPE_KEY_TEST | Development, Testing | Yes | Your Stripe API test key | |
STRIPE_TEST | Development, Testing | No | 0 | Set to 1 if STRIPE_KEY_TEST is filled |
DEBUG | Development | No | 0 | Set to 1 for development |
TEST | Testing | No | 0 | Set to 1 for testing |
cp LaBoutik/env_example LaBoutik/.env
| Name | Target environment | Nullable | Default value | Notes |
|---|---|---|---|---|
SECRET_KEY | All | No | One of the previously generated Django secret key | |
FERNET_KEY | All | No | One of the previously generated Fernet key | |
DOMAIN | All | No | laboutik.tibillet.localhost | Change to you domain and subdomain for production mode |
FEDOW_URL | All | No | https://fedow.tibillet.localhost/ | Fedow engine URL |
LESPASS_TENANT_URL | All | No | https://lespass.tibillet.localhost/ | Lespass instance URL |
TIME_ZONE | All | No | Europe/Paris | TZ time zone of the instance |
ADMIN_EMAIL | All | No | Admin email (for the first admin) | |
MAIN_ASSET_NAME | All | No | Name of your main cashless asset (Centiment, HeartBit… whatever you like) | |
POSTGRES_DB | All | No | laboutik | Change for production mode if necessary |
POSTGRES_USER | All | No | laboutik_user | Change for production mode |
POSTGRES_PASSWORD | All | No | Strong password (one of the Fernet keys for example) | |
EMAIL_HOST, EMAIL_PORT, EMAIL_HOST_USER, EMAIL_HOST_PASSWORD | All | Yes | Email server, required to confirm user registrations for example | |
BORG_PASSPHRASE | All | Yes | Password used for data backup | |
DEBUG | Development | No | 0 | Set to 1 for development |
TEST | Testing | No | 0 | Set to 1 for testing |
DEMO | Development, Testing | No | 0 | Set to 1 for a register simulation |
SENTRY_DNS | Development, Testing | Yes | Sentry Debug pour le back-end | |
SENTRY_FRONT_DNS, SENTRY_FRONT_ASSET | Development, Testing | Yes | Sentry Debug for front-end | |
DEMO_TAGID_CM, DEMO_TAGID_CLIENT1, DEMO_TAGID_CLIENT2 | Yes | No idea |
The configuration should now be complete for the TiBillet engines.
For… reasons, the entire dev environment is assembled through the tests. The setup of the testing repository might seem familiar:
@@ -85,18 +88,38 @@This particular docker-compose.yml relies on the folder structure of its parent folder shown in the beginning with the example name of tibillet-dev. Counterintuitive, but hey: now you know!
The main difference between dev and prod containers is that running the docker compose command will not start the individual Django apps. It's a level of granularity that helps with development, but it means you get to start them manually by entering the containers. Lucky you! 🍀
Let's do a bit of a shell-ception: we're going to enter a bash shell inside a Docker container, then from there enter the Poetry virtual environment. For example with Fedow:
-docker exec -ti fedow_django bash # entering the container
poetry shell # entering the virtual environment
Were're gonna start them in a particular order:
+The tools we need are in the Django containers, named after the engines: fedow_django, lespass_django and laboutik_django. To enter a container (Fedow example) :
# starting bash shell in fedow_django container
docker exec -ti fedow_django bash
From there we have a few options.
-./flush.sh # will start the Django app from scratch with test data
rsp # alias to 'python manage.py runserver 0.0.0.0:8000' if you want to keep your data
./manage.py collectstatic # sometimes static assets do not get collected properly in the first startup, which makes it look like a website from the 90s. if that happens, run this
The django containers are by default named after the engines: fedow_django, lespass_django, laboutik_django. Manually start them all!
First is the flush.sh script. It initializes testing data and starts the app right after. This is what we're gonna use at first boot:
./flush.sh
We will also use it when we want to reset data, for example before starting the automated testing with relies on this predictible data.
+For the rest of the container manipulations, we're going to need the Poetry shell, because we're gonna use Python commands.
+To start Poetry's virtual env from the container:
+ # we start the virtual env that handles the python dependencies
poetry shell
Django is handled through a script called manage.py. Two commands are of interest to us here:
rsp (alias of ./manage.py runserver 0.0.0.0:8000) starts Django but doesn't wipe out the data. This will help keep data between sessions. GThis command is used in most cases, flush is only used for testing or when something's gonz wrong.
As an option, if you're encontering graphical issues (such as assets not loading), you can attempt ./manage.py collectstatic. Sometimes the graphical assets are not properly collected at first boot, in which case this can help.
Only thing left to do is to start the three engines in the order described earlier : Fedow, Lespass, then LaBoutik !
The docker command gets repetitive after a while. Why not create an alias, or even a little bash function that will shorten your labor and preserve your carpal tunnel? Here's mine:
function dockex {
docker exec -ti $1 bash
}
There's probably even a way to add the poetry stuff to it, look it up!
If you have used the default domain configuration, you can now access:
If everything is working as expected, congratulations: you're ready to go 🔧
If not, come talk to us, we'd love to help!
@@ -106,11 +129,11 @@docker compose pull
docker compose up -d # start or restart the updated containers
You can run the Python tests through the same shell-ception required to do a manual start. Start by flushing the 3 Django apps to get fresh testing data, then run this inside your Laboutik Django container:
+You can run the Python tests through the same shell-ception required to do a manual start. Start by flushing the 3 Django apps to get fresh testing data, then run this inside your LaBoutik Django container:
./manage.py test
Before causing any major change, backup any data that has value to your development. On your Fedow instance, you only need to save the database folder regularly. The other engines can be backed up through the Borgbackup util, cron tasks and database dumps. More about this in the future.