Commit bc3f0ca4 authored by Guillaume Bernard's avatar Guillaume Bernard

docs: switch README to Markdown syntax

parent 946f1583
Pipeline #57387 passed with stage
in 3 minutes and 41 seconds
Damned-Lies is a translation-tracking Web application originally aimed
to help the GNOME Translation project. It is written in Python based on
the Django framework.
You can find the Data model in the /docs directory.
Requirements
============
1 - Django > 2.0.X
2 - Python 3.4 (minimal)
pillow (python-pillow) for hackergotchi checks.
Markdown (python-markdown) for Team presentation markup rendering.
translate-toolkit >= 2.2
3 - gettext, intltool, gnome-doc-utils (for stats generation), itstool,
yelp-tools, yelp-xsl
4 - [Optional] Django Debug Toolbar
git clone git://github.com/jazzband/django-debug-toolbar.git
Define USE_DEBUG_TOOLBAR to True in local_settings.py to use it.
5 - [Optional] python-pyicu for correct sorting in various languages
Installing all requirements using pip:
pip install -r requirements.txt
Installation
============
1 - Create a damnedlies/local_settings.py and overwrite settings to match your
requirements and your configuration layouts. Typical settings to customize
include:
DATABASES, SECRET_KEY, DEBUG, STATIC_SERVE, ADMINS, ADMIN_GROUP,
SITE_DOMAIN, SCRATCHDIR, and various EMAIL settings.
Please refer to Database configuration below for more information.
SCRATCHDIR should point to an existing directory, writable by the web
application user.
Note also that if you don't want to really send mail when testing the app,
you can set the EMAIL_BACKEND setting as follows to redirect mail to the
console:
EMAIL_BACKEND = 'django.core.mail.backends.console.EmailBackend'
2 - Run the following command to execute the database migrations:
./manage.py migrate
3 - In production, you will have to run the following command:
./manage.py collectstatic
Then configure your Web server to statically serve this directory. For
example, with Apache, a simple alias directive is enough:
Alias /static /absolute/path/to/djamnedlies/static
4 - (optional) If you want to populate the database with sample data, run:
./manage.py loaddata sample_data
5 - You should now be able to launch the server to check if all is running well:
./manage.py runserver
6 - Configure Sites in admin interface ('View on site' link, site address in
sent mail).
Running tests
=============
To execute the tests, run this command:
python manage.py test [optional path to run partial tests]
Read https://docs.djangoproject.com/en/stable/topics/testing/ for more details
about testing in Django projects.
Maintenance tasks
=================
There is a management command to run maintenance tasks (clean never-activated
accounts, inactivate unused roles, ...):
./manage.py run-maintenance
It might be useful to add the command in a cron schedule.
Databases
=========
It's important to use the Unix Domain Socket connection to obtain good
performances.
PostgreSQL
----------
In the DATABASES['default'] dictionary, you just need to define
ENGINE = 'django.db.backends.postgresql_psycopg2' and the NAME key.
Leave HOST setting empty to use UDS.
MySQL
-----
Create a database in UTF8, either with default-character-set = utf8
under [mysqld] section in the my.cnf file or with an explicit 'create
database bla charset=utf8;'
In local_settings.py:
DATABASES = {
'default' {
'ENGINE': 'django.db.backends.mysql',
'NAME': '<your database name>',
'USER': '<your user>',
'PASSWORD': '<your password>',
'HOST' = '/var/run/mysqld/mysqld.sock',
'OPTIONS' = {
'read_default_file': '/etc/mysql/my.cnf',
}
}
}
Grep for ANSI_QUOTES in the source code to find the models.py which
use a hack to workaround the double quotes interpretation in MySQL.
The best solution is to run the MySQL server with the ANSI_QUOTES
mode: http://dev.mysql.com/doc/refman/5.7/en/sql-mode.html
(sql-mode="ANSI_QUOTES" in my.cnf) but it can be dangerous for other
applications.
Translations
============
To be able to also extract strings from various database fields, a
wrapper script has been created around standard Django
make_messages. The script also copy po files in /po directory.
Run 'python manage.py update-trans' to update translations when there
are string changes.
After translation files in po directory have been updated, there is
another script to put back po files in
locale/<ll>/LC_MESSAGES/django.po and call Django's compile_messages
command.
Run 'python manage.py compile-trans'.
**Damned-Lies** is a translation-tracking Web application originally aimed to help the **GNOME Translation project**. It is written in Python based on the Django framework.
You can find the Data model in the `/docs` directory.
# Installation
* Create a `damnedlies/local_settings.py` and overwrite settings to match your requirements and your configuration layouts. Typical settings to customize include: `DATABASES`,`SECRET_KEY`, `DEBUG`, `STATIC_SERVE`, `ADMINS`, `ADMIN_GROUP`, `SITE_DOMAIN`, `SCRATCHDIR`, and various `EMAIL` settings.
* Please refer to [database configuration](Databases) below for more information.
* `SCRATCHDIR` should point to an existing directory, writable by the web application user.
* Note also that if you don't want to really send mail when testing the app, you can set the `EMAIL_BACKEND` setting as follows to redirect mail to the console: `EMAIL_BACKEND = 'django.core.mail.backends.console.EmailBackend'`
## Manual installation
### Install requirements
In order to install Damned-Lies, you’ll need to install the following components:
1. `Django > 2.0.X`
2. Python 3.4 (minimal)
pillow (`python-pillow`) for hackergotchi checks.
Markdown (python-markdown) for Team presentation markup rendering.
`translate-toolkit >= 2.2`
3. `gettext`, `intltool`, `gnome-doc-utils` (for stats generation), `itstool`, `yelp-tools`, `yelp-xsl`
4. [Optional] Django Debug Toolbar
```bash
git clone git://github.com/jazzband/django-debug-toolbar.git
```
Define `USE_DEBUG_TOOLBAR` to `True` in `local_settings.py` to use it.
5. **Optional** `python-pyicu` for correct sorting in various languages
Installing all requirements using pip:
```sh
pip install -r requirements.txt
```
### Run Django
1. Run the following command to execute the database migrations:
```bash
./manage.py migrate
```
2. In production, you will have to run the following command:
```bash
./manage.py collectstatic
```
Then configure your Web server to statically serve this directory. For example, with Apache, a simple alias directive is enough:
```apacheconf
Alias /static /absolute/path/to/djamnedlies/static
```
3. (optional) If you want to populate the database with sample data, run:
```bash
./manage.py loaddata sample_data
```
4. You should now be able to launch the server to check if all is running well:
```bash
./manage.py runserver
```
5. Configure Sites in admin interface ('View on site' link, site address in sent mail).
## Installation in Docker (for development purposes)
We provide an integrated procedure to deploy Damned Lies using Docker. This will be helpfull if you’d like to contribute, as the only thing you should use to run Damned Lies is:
```bash
docker-compose up
```
This command will build an image with all the requirements and start Damned Lies with sample data and a default root account with has the credentials `root` as login and `root` as password is created. You can access the Django administration panel using the `/admin` route.
*Note: do not try to go to Damned Lies if you’re connected as `root` unless you manually associated a Person instance with this Django user, otherwise you’ll get multiple errors.*
# Running tests
To execute the tests, run this command:
```bash
python manage.py test [optional path to run partial tests]
```
Read [Django Testing Documentation](https://docs.djangoproject.com/en/stable/topics/testing/) for more details about testing in Django projects.
# Maintenance tasks
There is a management command to run maintenance tasks (clean never-activated accounts, inactivate unused roles, ...):
```bash
./manage.py run-maintenance
```
It might be useful to add the command in a cron schedule.
# Databases
It's important to use the Unix Domain Socket connection to obtain good performances.
## PostgreSQL
In the `DATABASES['default']` dictionary, you just need to define `ENGINE = 'django.db.backends.postgresql_psycopg2'` and the `NAME` key. Leave `HOST` setting empty to use `UDS`.
## MySQL
Create a database in UTF8, either with `default-character-set = utf8` under `[mysqld]` section in the `my.cnf` file or with an explicit `create database bla charset=utf8;`
In `local_settings.py`:
```python
DATABASES = {
'default' {
'ENGINE': 'django.db.backends.mysql',
'NAME': '<your database name>',
'USER': '<your user>',
'PASSWORD': '<your password>',
'HOST' = '/var/run/mysqld/mysqld.sock',
'OPTIONS' = {
'read_default_file': '/etc/mysql/my.cnf',
}
}
}
```
Grep for `ANSI_QUOTES` in the source code to find the models.py which use a hack to workaround the double quotes interpretation in MySQL. The best solution is to [run the MySQL server with the `ANSI_QUOTES` mode](http://dev.mysql.com/doc/refman/5.7/en/sql-mode.html): (`sql-mode="ANSI_QUOTES"` in `my.cnf`) but it can be dangerous for other applications.
# Translations
To be able to also extract strings from various database fields, a pper script has been created around standard Django make_messages. The script also copy po files in `/po` directory.
Run `python manage.py update-trans` to update translations when there are string changes.
After translation files in po directory have been updated, there is another script to put back po files in `locale/<ll>/LC_MESSAGES/django.po` and call Django's compile_messages command.
Run `python manage.py compile-trans`.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment