bifurqué depuis cliss21/chronos
doc(README): complète et améliore la documentation
Parent
1ce66593bd
révision
b4c45ac86f
195
README.md
195
README.md
|
@ -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
|
||||
|
|
Fichier binaire non affiché.
Après Largeur: | Hauteur: | Taille: 12 KiB |
Chargement…
Référencer dans un nouveau ticket