README.md 5.41 KB
Newer Older
1
2
3
The COIN project
================

Baptiste Jonglez's avatar
Baptiste Jonglez committed
4
5
`Coin` is Illyse's Information System, designed to manage both members
and Internet accesses, such as through DSL, VPN, wireless…
6
7
8
9

It is written in Django, and makes an heavy use of LDAP (for
authentication, and to store configuration information).

Baptiste Jonglez's avatar
Baptiste Jonglez committed
10
11
12
13
14
It features a generic configuration interface, which allows to implement
custom backends for different technologies.  Currently implemented is a
LDAP-based backend for OpenVPN.

Coin currently only works with python2, because `python-ldap` is (as of
15
16
2013) not compatible with python3.

Baptiste Jonglez's avatar
Baptiste Jonglez committed
17
18
19
20
21
22
23
24
The project page (issue, wiki, etc) is here:

  https://www.illyse.org/projects/ils-si/

A mirror of the code is available at:

  https://code.ffdn.org/zorun/coin/

25

26
27
28
29
30
31
32
33
34
35
36
37
38
Demo
====

A demo of COIN is publicly available at:

  https://coin-dev.illyse.org

Login: ffdn
Password: internet

This user account has access to the administration interface.


Baptiste Jonglez's avatar
Baptiste Jonglez committed
39
40
Quickstart
==========
41

42
43
44
45
46
Virtualenv
----------

Using a virtualenv is recommended.  On Debian, install `python-virtualenv`.
On Archlinux, the package is called `python2-virtualenv`, and you must
47
48
49
50
51
52
53
54
55
56
57
58
59
60
replace the `virtualenv` command with `virtualenv2` in the following.

To create the virtualenv (the first time):

  virtualenv ~/tmp/venv-illyse


To activate the virtualenv (you need to do this each time you work on
the project):

  . ~/tmp/venv-illyse/bin/activate


Install dependencies. On Debian, you will probably need the
61
62
`python-dev`, `python-pip`, `libldap-dev`, `libpq-dev` and `libsasl2-dev`
packages.
Fabs's avatar
Fabs committed
63

64
  sudo apt-get install python-dev python-pip libldap2-dev libpq-dev libsasl2-dev
Fabs's avatar
Fabs committed
65
66

Then run:
67
68
69

  pip install -r requirements.txt

70
You may experience problems with SSL certificates du to self-signed cert used by code.ffdn.org. You can temporarily disable certificate verification in git : git config --global http.sslVerify false
71
72
73

You should now be able to run `python manage.py` (within the
virtualenv, obviously) without error.
Baptiste Jonglez's avatar
Baptiste Jonglez committed
74

75
76
77
Settings
--------

78
The `coin/settings_local.py` file is ignored by Git: feel free to override any
79
80
81
82
83
84
setting by writing into that file. For example, to override the `DEBUG`
settings:

    echo '# -*- coding: utf-8 -*-' > coin/settings_local.py
    echo 'DEBUG = TEMPLATE_DEBUG = True' >> coin/settings_local.py

85
If you don't want to use LDAP, just set in your `settings_local.py`:
86

87
    LDAP_ACTIVATE = False
88

89
90
91
92
93
94
95
96
97
98
99
100
101
102
See the end of this README for a reference of available configuration settings.

Database
--------

At this point, you should setup your database: we highly recommend PostgreSQL.
SQLite might work, but some features will not be available:

- automatic allocation of IP subnet

For more information on the database setup, see:

  https://www.illyse.org/projects/ils-si/wiki/Mise_en_place_environnement_de_dev

103
104
The first time, you need to create the database, create a superuser, and
import some base data to play with:
105

106
107
108
    python manage.py migrate
    python manage.py createsuperuser
    python manage.py loaddata offers ip_pool
109

Baptiste Jonglez's avatar
Baptiste Jonglez committed
110
111
112
113
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).

114
115
Then, at each code update, you will only need to update dependencies and apply
new migrations:
Fabs's avatar
Fabs committed
116

117
    pip install -r requirements.txt
118
    python manage.py migrate
Fabs's avatar
Fabs committed
119

120
121
122
123

At this point, Django should run correctly:

    python manage.py runserver
Fabs's avatar
Fabs committed
124
125


126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
Available commands
==================

Some useful administration commands are available via `manage.py`.

`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.

141
142
143
144
145
`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.

146

147
148
149
150
151
152
Configuration
=============

You should first setup the `sites` application, in the admin.  The domain name
configured there is used for outgoing emails.

153
ISP-specific configuration
154
--------------------------
155
156
157
158
159
160
161
162
163
164
165
166

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.

167
168
169
170
171
172
173
174
175
Cron tasks
----------

You may want to run cron jobs for repetitive tasks.

To generate invoices on the first day of each month, here at 3 am:

`0 3 1 * * /home/coin/venv/bin/python manage.py charge_subscriptions`

176
177
178
179
To send reminder emails for membership fee expiration:

`42 3 * * * /home/coin/venv/bin/python manage.py call_for_membership_fees`

180

Baptiste Jonglez's avatar
Baptiste Jonglez committed
181
182
183
184
185
186
More information
================

For the rest of the setup (database, LDAP), see

  https://www.illyse.org/projects/ils-si/wiki/Mise_en_place_environnement_de_dev
Baptiste Jonglez's avatar
Baptiste Jonglez committed
187
188

For real production deployment, see file `DEPLOYMENT.md`.