bifurqué depuis cliss21/chronos
1
0
Bifurcation 0

doc(README): complète et améliore la documentation

master
Jérôme Lebleu 2019-08-22 12:09:01 +02:00
Parent 1ce66593bd
révision b4c45ac86f
2 fichiers modifiés avec 135 ajouts et 60 suppressions

195
README.md
Voir le fichier

@ -1,43 +1,48 @@
# Chronos - README
# ![Chronos](artwork/chronos.png)
gestion et organisation du temps
**Chronos** est une application Web visant à faciliter la saisie, la validation
et le suivi de l'agenda des personnes d'une organisation. Elle est pensée pour
s'adapter autant que possible à la composition et la hiérarchie interne de
l'organisation.
## Early build for development
In early stage of development, database and assets
are not yet fixed so building the project involve a little more
steps:
**Table of content**
1. assume `git clone` is done and `npm` is installed
- [Give a try](#give-a-try)
- [Installation](#installation)
- [Deployment](#deployment)
- [Structure](#structure)
- [Development](#development)
2. `make build` (may crash due to incomplete migrations - ignore error)
## Give a try
3. `make reset-migrations` (remove database, local migration, redo it, install some fixtures)
On a Debian-based host - running at least Debian Stretch:
4. `npm install` (install all the assets dependancies)
5. `npm run build` (create assets)
```
$ sudo apt install python3 virtualenv git make
$ git clone https://forge.cliss21.org/cliss21/chronos
$ cd chronos/
$ make init
6. Use it! `make serve` / `make test` ...
A configuration will be created interactively; uncomment
ENV=development
### keep it up to date
$ make test # optional
$ make serve
```
1. `git pull` (or `git fetch` + `git merge`)
2. `make update` (install new python dependancies if needed, may crash due to incompletes migrations - ignore error)
3. `make reset-migrations` (re-create database from scratch)
4. `npm install` / `npm run build` update assets if needed
5. Use it! `make serve` / `make test` ...
Then visit [http://127.0.0.1:8000/](http://127.0.0.1:8000/) in your web browser.
## Installation
### Requirements
On a Debian-based host - running at least Debian Stretch, you will need the
following packages:
- python3
- virtualenv
- make
- git (recommended for getting the source)
- python3-mysqldb (optional, in case of a MySQL / MariaDB database)
- python3-psycopg2 (optional, in case of a PostgreSQL database)
### Quick start
@ -58,40 +63,7 @@ way is by cloning this repository - and that you are in this folder.
That's it! Your environment is now initialized with the application installed.
To update it, once the source code is checked out, simply run `make update`.
### Deployment
Here is an example deployment using NGINX - as the Web server - and uWSGI - as
the application server.
The uWSGI configuration doesn't require a special configuration, except that we
are using Python 3 and a virtual environment. Note that if you serve the application
on a sub-location, you will have to add `route-run = fixpathinfo:` to your uWSGI configuration (from
[v2.0.11](https://uwsgi-docs.readthedocs.io/en/latest/Changelog-2.0.11.html#fixpathinfo-routing-action)).
In the `server` block of your NGINX configuration, add the following blocks and
set the path to your application instance and to the uWSGI socket:
```
location / {
include uwsgi_params;
uwsgi_pass unix:<uwsgi_socket_path>;
}
location /media {
alias <app_instance_path>/var/media;
}
location /static {
alias <app_instance_path>/var/static;
# Optional: don't log access to assets
access_log off;
}
location = /favicon.ico {
alias <app_instance_path>/var/static/favicon/favicon.ico;
# Optional: don't log access to the favicon
access_log off;
}
```
You should also check that your application is well configured by running
You can also check that your application is well configured by running
`make check`.
### Manual installation
@ -134,13 +106,47 @@ check that everything is working fine with:
$ ./manage.py runserver
## Deployment
Here is an example deployment using NGINX - as the Web server - and uWSGI - as
the application server.
The uWSGI configuration doesn't require a special configuration, except that we
are using Python 3 and a virtual environment. Note that if you serve the
application on a sub-location, you will have to add `route-run = fixpathinfo:`
to your uWSGI configuration (from
[v2.0.11](https://uwsgi-docs.readthedocs.io/en/latest/Changelog-2.0.11.html#fixpathinfo-routing-action)).
In the `server` block of your NGINX configuration, add the following blocks and
set the path to your application instance and to the uWSGI socket:
```
location / {
include uwsgi_params;
uwsgi_pass unix:<uwsgi_socket_path>;
}
location /media {
alias <app_instance_path>/var/media;
}
location /static {
alias <app_instance_path>/var/static;
# Optional: don't log access to assets
access_log off;
}
location = /favicon.ico {
alias <app_instance_path>/var/static/favicon/favicon.ico;
# Optional: don't log access to the favicon
access_log off;
}
```
## Structure
### Overview
All the application files - e.g. Django code including settings, templates and
statics - are located into the `chronos/`. It should
permit in a near future to distribute the application as a Python package and
install it system-wide.
statics - are located into the `chronos/` directory. It should permit in a near
future to distribute the application as a Python package and install it
system-wide.
Two environments are defined - either for requirements and settings:
- `development`: for local application development and testing. It uses a
@ -183,6 +189,75 @@ There is some additional rules when developing, which are mainly wrappers for
- `make test`: test the whole application
- `make lint`: check the Python code syntax
### Assets
The assets - e.g. CSS, JavaScript, images, fonts - are generated using a
[Gulp](https://gulpjs.com/)-powered build system with these features:
- SCSS compilation and prefixing
- JavaScript module bundling with webpack
- Styleguide and components preview
- Built-in BrowserSync server
- Compression for production builds
The source files live in `assets/`, and the styleguide in `styleguide/`.
#### Requirements
You will need to have [npm](https://www.npmjs.com/) installed on your system.
If you are running Debian, do not rely on the npm package which is either
outdated or removed - starting from Debian Stretch. Instead, here is a way
to install the last version as a regular user:
1. Ensure that you have the following Debian packages installed, from at least
`stretch-backports`:
- nodejs
- node-rimraf
2. Set the npm's installation prefix as an environment variable:
$ export npm_config_prefix=~/.node_modules
3. Retrieve and execute the last npm's installation script:
$ curl -L https://www.npmjs.com/install.sh | sh
4. Add the npm's binary folder to your environment variables:
$ export PATH="${HOME}/.node_modules/bin:${PATH}"
In order to keep those environment variables the next time you will log in,
you can append the following lines to the end of your `~/.profile` file:
```bash
if [ -d "${HOME}/.node_modules/bin" ] ; then
PATH="${HOME}/.node_modules/bin:${PATH}"
export npm_config_prefix=~/.node_modules
fi
```
5. That's it! You can check that npm is now installed by running the following:
$ npm --version
#### Usage
Start by installing the application dependencies - which are defined in
`package.json` - by running: `npm install`.
The following tasks are then available:
- `npm run build`: build all the assets for development and production use,
and put them in the static folder - e.g `chronos/static`.
- `npm run styleguide`: run a server with the styleguide and watch for file
changes.
- `npm run serve`: run a proxy server to the app - which must already be served on
`localhost:8000` - with the styleguide on `/styleguide` and watch for file
changes.
- `npm run lint`: lint the JavaScript and the SCSS code.
In production, only the static files will be used. It is recommended to commit
the compiled assets just before a new release only. This will prevent to have a
growing repository due to the minified files.
## License
Chronos is developed by Cliss XXI and licensed under the

BIN
artwork/chronos.png Normal file

Fichier binaire non affiché.

Après

Largeur:  |  Hauteur:  |  Taille: 12 KiB