|jocelyn a058d014eb Merge branch 'fix-98-no-price-in-label' of daimrod/coin into master||2 years ago|
|coin||2 years ago|
|contrib||3 years ago|
|hardware_provisioning||2 years ago|
|simple_dsl||4 years ago|
|vpn||2 years ago|
|.gitignore||2 years ago|
|DEPLOYMENT.md||2 years ago|
|EXTENDING.md||2 years ago|
|README.md||2 years ago|
|manage.py||5 years ago|
|requirements.txt||2 years ago|
|setup.cfg||2 years ago|
Coin is Illyse's Information System, designed to manage both members
and Internet accesses, such as through DSL, VPN, wireless…
It is written in Django, and features a generic configuration interface, which allows to implement custom backends for different technologies. Currently implemented is a LDAP-based backend for OpenVPN, and a very simple DSL backend, without any authentication (useful for "white label" DSL).
Coin currently only works with python2, because
python-ldap is (as of
2013) not compatible with python3.
The project page (issue, wiki, etc) is here:
A mailing list is available, for both users and developers: https://listes.illyse.org/wws/info/si
If you want to write your own backend, see
Using a virtualenv is recommended. On Debian, install
On Archlinux, the package is called
python2-virtualenv, and you must
virtualenv command with
virtualenv2 in the following.
To create the virtualenv (the first time):
To activate the virtualenv (you need to do this each time you work on the project):
Install dependencies. On Debian, you will probably need the
sudo apt-get install python-dev python-pip libldap2-dev libpq-dev libsasl2-dev libjpeg-dev libxml2-dev libxslt1-dev libffi-dev
You need a recent pip for the installation of dependencies to work. If you don't meet that requirement (Ubuntu trusty does not), run:
pip install "pip>=1.5.6"
In any case, you then need to install coin python dependencies:
pip install -r requirements.txt
You should now be able to run
python manage.py (within the
virtualenv, obviously) without error.
coin/settings_local.py file is ignored by Git: feel free to override any
setting by writing into that file. For example, to override the
echo '# -*- coding: utf-8 -*-' > coin/settings_local.py echo 'DEBUG = TEMPLATE_DEBUG = True' >> coin/settings_local.py
See the end of this README for a reference of available configuration settings.
At this point, you should setup your database. The default setting uses SQLite but some features will not be available, namely:
If you want to use those features, you will need to setup a PostgreSQL database.
For more information on the database setup, see https://www.illyse.org/projects/ils-si/wiki/Mise_en_place_environnement_de_dev
The first time, you need to create the database, create a superuser, and import some base data to play with:
python manage.py migrate python manage.py createsuperuser python manage.py loaddata offers ip_pool # skip this if you don't use PostgreSQL
Note that the superuser will be inserted into the LDAP backend exactly in the same way as all other members, so you should use a real account (not just admin/admin).
Then, at each code update, you will only need to update dependencies and apply new migrations:
pip install -r requirements.txt python manage.py migrate
At this point, Django should run correctly:
python manage.py runserver
There is a set of unit tests you can run with :
DJANGO_SETTINGS_MODULE=coin.settings_test ./manage.py test
LDAP-related tests are disabled by default.
Setup LDAP parameters and activate LDAP in settings to make the LDAP tests run.
pip install pytest-django
Some useful administration commands are available via
python manage.py members_email: returns email addresses of all members, one
per line. This may be useful to automatically feed a mailing list software.
Note that membership is based on the
status field of users, not on
membership fees. That is, even if a member has forgot to renew his or her
membership fee, his or her address will still show up in this list.
python manage.py charge_subscriptions: generate invoices (including a
PDF version) for each subscriber. You probably want to run this command
every month as a cron task, see below.
python manage.py call_for_membership_fees: send reminder emails to members
whose membership fee is about to expire or is already expired (1 month before,
on the day of expiration, 1 month after, 2 months after, and 3 months after).
You should run this command in a cron job every day.
python manage.py offer_subscriptions_count: Returns subscription count grouped
by offer type.
You should first setup the
sites application, in the admin. The domain name
configured there is used for outgoing emails.
By default, LDAP support is disabled. If you want to use LDAP (for
instance for the OpenVPN/LDAP backend, or for your own backend), see the
The main place to customize Coin for your ISP is the IspDatabase application, in the admin. Information entered in this application has two purposes:
1) generate a JSON file usable by http://db.ffdn.org/
2) customize the user interface (postal address, bank account, ISP name & logo...)
Some bits of configuration are done in
settings.py: LDAP branches, RSS feeds
to display on the home page, and so on. Lastly, it is possible to override
all Coin templates (i.e. for user views and emails), see below.
Coin sends mails, you might want to customize the sender address:
DEFAULT_FROM_EMAILfor administrative emails (welcome email and membership fees), will take precedence (if filled).
You may want to run cron jobs for repetitive tasks.
The command that generates invoices should be run every day, so that invoices for new subscriptions are created automatically. On the first day of each month, invoices will be generated for all subscriptions. This will run the command at 23:59 every day:
59 23 * * * /home/coin/venv/bin/python manage.py charge_subscriptions`
To send reminder emails for membership fee expiration:
42 3 * * * /home/coin/venv/bin/python manage.py call_for_membership_fees`
If you want to be notified by email each time a reminder email is sent, you can set an email address in the crontab:
You may want to override some of the (HTML or email) templates to better suit your structure needs.
Coin allows you to have a folder of custom templates that will contain your templates, which gets loaded prior to coin builtins.
With this method, several templates can be overridden:
coin/<app_name>/templates/for all active applications
For instance, in
EXTRA_TEMPLATE_DIRS = ('/home/coin/my-folder/templates',)
Copy the template you want to override to the right place in your custom folder (that's the hard part, see the example).
Say we want to override the template located at
coin/members/templates/members/emails/call_for_membership_fees.html and we
EXTRA_TEMPLATE_DIRS = ('/home/coin/my-folder/templates',) in settings.
Then make a copy of the template file (and customize it) at
Good to go :-)
Some apps are not enabled by default :
You can enable them using the
EXTRA_INSTALLED_APPS = ( 'vpn', )
If you enable an extra-app after initial installation, make sure to sync database :
nb: extra apps are loaded after the builtin apps.
List of available settings in your
EXTRA_INSTALLED_APPS: See Customizing app list
EXTRA_TEMPLATE_DIRS: See Customizing templates
LDAP_ACTIVATE: See LDAP
MEMBER_MEMBERSHIP_INFO_URL: Link to a page with information on how to become a member or pay the membership fee
SUBSCRIPTION_REFERENCE: Pattern used to display a unique reference for any subscription. Helpful for bank wire transfer identification
For the rest of the setup (database, LDAP), see https://doc.illyse.net/projects/ils-si/wiki/Mise_en_place_environnement_de_dev
For real production deployment, see file