Transparency: detail costs for libre price
==========================================

It's still alpha-pre-ugly-looking and some strings are mentioning
[FAImaison](https://faimaison.net). A more usable version may be
integrated to [coin](https://code.ffdn.org/ffdn/coin).

Install it
----------

Be sure to use python3

    sudo apt-get install python virtualenv

Create a dedicated virtualenv:

    virtualenv transparency_venv

Clone this repository:

    git clone https://code.ffdn.org/jocelyn/transparency
    cd transparency
    source ../transparency_venv/bin/activate
    pip install -r requirements.txt

Generate a secret key:

    echo SECRET_KEY=`python -c "import string,random; uni=string.ascii_letters+string.digits+string.punctuation; print(repr(''.join([random.SystemRandom().choice(uni) for i in range(random.randint(45,50))])))"` > transparency/local_settings.py

Create database:

    ./manage.py migrate

Create administrator account:

    ./manage.py createsuperuser

Run it
------

Activate your virtualenv if needed / if it is not already done:

    source ../transparency_venv/bin/activate

As far as you stay in development mode, you can activate `DEBUG` mode to
avoid `settings.ALLOWED_HOSTS` error:

    echo 'DEBUG=True' >> transparency/local_settings.py

Please [read the Django deployment checklist][1] before trying to push
your transparency website in production.

[1]: https://docs.djangoproject.com/en/2.1/howto/deployment/checklist/

Finally, run development server:

    ./manage.py runserver

Use it
------

- Enter data into (yeah, documentation can explain a bit better…)
  http://localhost:8000/admin/
- Browse http://localhost:8000 to view costs/details

Custom settings
---------------

All your custom settings should go to the
`transparency/local_settings.py` file. By default it does not exists,
thus you have to create it (but if you follow the installation guide
above, it is already there). As its extension proves, it is a regular
python file. The basic way to add your customized option is just to list
your variables and their values:

```python
MYVAR = "my custom value"
```

But, as it is a python file, you are free to do more complex stuff:

```python
import totallyotherpackage

def my_custom_value_computation:
    toto = "tata"
    return toto + totallyotherpackage.funny_stuff()

MYVAR = my_custom_value_computation()
```

The rest of this section present some of the available options you may
want to customize to fit your needs:

| Name                           | Description                                                                          | Default value         | Note                    |
|--------------------------------|--------------------------------------------------------------------------------------|-----------------------|-------------------------|
| `SECRET_KEY`                   | [Django secret key][2]. You should have set it during the setup, as described above. | `None`                | **required**            |
| `DEBUG`                        | [Django debug mode][3]                                                               | `False`               | *development mode only* |
| `ORGANIZATION_NAME`            | Name of your organization, for which you want to edit transparency reports.          | `"Transparency inc."` |                         |
| `SETUP_COST_STAGGERING_MONTHS` | How many months do you want setup costs to be staggering accross                     | `36`                  |                         |
| `PROVISIONING_DURATIONS`       | What provisionning durations will be available in the report forms.                  | See below             |                         |
| `RESOURCES_UNITS`              | What resources units will be available in the report forms.                          | See below             |                         |

[2]: https://docs.djangoproject.com/en/2.1/ref/settings/#std:setting-SECRET_KEY
[3]: https://docs.djangoproject.com/en/2.1/ref/settings/#std:setting-DEBUG

Both `PROVISIONING_DURATIONS` and `RESOURCES_UNITS` are lists of
tuples. Their default values are respectively:

```python
PROVISIONING_DURATIONS = [
    (datetime.timedelta(days=365*3), '3 ans'),
    (datetime.timedelta(days=365*5), '5 ans'),
]

RESOURCES_UNITS = [
    ('a', 'A'),
    ('mbps', 'Mbps'),
    ('u', 'U'),
    ('ipv4', 'IPv4'),
    ('eth', 'ports'),
    ('services', 'abonnement')
]
```

You can totally overwrite them:

```python
RESOURCES_UNITS = [
    ('server', 'Serveurs'),
    ('cube', 'Brique')
]
```

Or just add new possibility, like this:

```python
PROVISIONING_DURATIONS.append((datetime.timedelta(days=182), '6 mois'))
```

or this:

```python
PROVISIONING_DURATIONS += [
    (datetime.timedelta(days=182), '6 mois'),
    (datetime.timedelta(days=365*8), '8 ans'),
]
```

**Warning:** please note that the first element of each
`RESOURCES_UNITS` tuple will be stored in the database as a string,
which must be **10** characters long at most.

You must note too, that the first element of each
`PROVISIONING_DURATIONS` tuple should be a `datetime.timedelta` object
or, at least, something having a `days` attribute, storing an integer.