doc(README): mets à jour la doc d'install et de dev.

pull/2/head
Jérôme Lebleu 2019-03-25 16:41:30 +01:00 commité par Jérôme Lebleu
Parent 33460132a6
révision 4d93b26b44
1 fichiers modifiés avec 150 ajouts et 11 suppressions

161
README.md
Voir le fichier

@ -1,22 +1,47 @@
# Boite à Asso
La plateforme numérique de l'Association d'Action Éducative du Pas-de-Calais.
La plate-forme numérique de l'Association d'Action Éducative du Pas-de-Calais.
**Table of content**
- [Installation](#installation)
- [Deployment](#deployment)
- [Structure](#structure)
- [Development](#development)
## Installation
### Requirements
On a Debian-based host - running at least Debian Jessie, you will need the
On a Debian-based host - running at least Debian Stretch, you will need the
following packages:
- python3
- virtualenv
- python3-psycopg2 (optional, in case of a PostgreSQL database)
### Step by step
### Quick start
In waiting for a complete `Makefile`, you will have to follow those steps to
install the application.
It assumes that you already have the application source code locally - the best
way is by cloning this repository - and that you are in this folder.
It assumes that you have downloaded the last release of Plateforme de l'AAE62,
extracted it and that you moved to that folder.
1. Define your local configuration in a file named `config.env`, which can be
copied from `config.env.example` and edited to suits your needs.
Depending on your environment, you will have to create your database and the
user at first.
2. Run `make init`.
Note that if there is no `config.env` file, it will be created interactively.
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`.
### Manual installation
If you don't want to use the `Makefile` facilities, here is what is done behind the scene.
It assumes that you have downloaded the last release of Boite à Asso, extracted
it and that you moved to that folder.
1. Start by creating a new virtual environment under `./venv` and activate it:
@ -35,10 +60,11 @@ extracted it and that you moved to that folder.
$ cp config.env.example config.env
$ nano config.env
$ chmod go-rwx config.env
Note that this `./config.env` file will be loaded by default when the
application starts. If you don't want that, just move this file away or set
the `DJANGO_READ_CONFIG_FILE` environment variable to `false`.
the `READ_CONFIG_FILE` environment variable to `0`.
4. Create the database tables - it assumes that you have created the database
and set the proper configuration to use it:
@ -50,6 +76,37 @@ 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;
}
```
You should also check that your application is well configured by running
`make check`.
## Structure
### Overview
@ -85,7 +142,89 @@ So, you will have to configure your Web server to serve the `var/media/` and
`var/static/` folders, which should point to `/media/` and `/static/`,
respectively.
## Licence
## Development
Cette application est développée par [Cliss XXI](http://www.cliss21.com) sous
licence [AGPLv3+](LICENSE).
The easiest way to deploy a development environment is by using the `Makefile`.
Before running `make init`, ensure that you have either set `ENV=development`
in the `config.env` file or have this environment variable. Note that you can
still change this variable later and run `make init` again.
There is some additional rules when developing, which are mainly wrappers for
`manage.py`. You can list all of them by running `make help`. Here are the main ones:
- `make serve`: run a development server
- `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 `boiteaasso/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 `/stylguide` 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
Boite à Asso is developed by Cliss XXI and licensed under the [AGPLv3+](LICENSE).