doc(README): mets à jour la doc d'install et de dev.
Parent
33460132a6
révision
4d93b26b44
161
README.md
161
README.md
|
@ -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).
|
||||
|
|
Chargement…
Référencer dans un nouveau ticket