Reviewed-on: #43 |
2 weeks ago | |
---|---|---|
bin | 7 months ago | |
grapes | 2 weeks ago | |
requirements | 5 months ago | |
static_media/js | 14 years ago | |
.gitignore | 2 weeks ago | |
CHANGELOG.md | 3 weeks ago | |
CONTRIBUTORS.txt | 3 weeks ago | |
LICENSE | 3 weeks ago | |
Makefile | 7 months ago | |
README.fr.md | 3 weeks ago | |
README.md | 3 weeks ago | |
config.env.example | 7 months ago | |
manage.py | 7 months ago | |
pyproject.toml | 9 months ago | |
setup.cfg | 7 months ago |
README.md
🍇️ grAPES
🍇️ grAPES is a CRM free software designed for APES
Table of content
Give a try
On a Debian-based host - running at least Debian Buster:
$ sudo apt install python3 virtualenv git make
$ git clone https://forge.cliss21.org/cliss21/grAPES
$ cd grAPES/
$ make init
# A configuration file will be created interactively; you can uncomment:
# ENV=development
# $ make test # optional
$ make serve
Then visit 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
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.
-
Define your local configuration in a file named
config.env
, which can be copied fromconfig.env.example
and edited to suits your needs.Depending on your environment, you will have to create your database and the user at first.
-
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
.
You can also check that your application is well configured by running
make check
.
Deployment
The following documentation is about manual deployment.
Web application
NginX with uWSGI
Here is an example deployment using NGINX - as the Web server - and uWSGI - as the application server.
uWSGI
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 (available since v2.0.11).
NGINX
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;
}
Apache with mod_wsgi
Here is an example deployment using Apache as the Web server.
The WSGI configuration doesn't require a special configuration, except that we are using Python 3 and a virtual environment. See e.g. Django's docs for more details.
WSGIProcessGroup grapes
WSGIDaemonProcess grapes python-home=<app_instance_path>/venv/ python-path=<app_instance_path>/
WSGIScriptAlias / <app_instance_path>/grAPES/wsgi.py process-group=grapes
<Directory <app_instance_path>/grAPES/>
<Files wsgi.py>
Require all granted
</Files>
</Directory>
Alias /static/ <app_instance_path>/var/static/
<Directory <app_instance_path>/var/static/>
Require all granted
</Directory>
Alias /media/ <app_instance_path>/var/media/
<Directory <app_instance_path>/var/media/>
Require all granted
</Directory>
Alias /favicon.ico <app_instance_path>/var/static/favicon/favicon.ico
Checking for new releases
Once you deployed 🍇️ grAPES, you can check for new release using
$ ./manage.py check_update
Giving --warn
option you get error code when a new release is available.
Structure
Overview
All the application files - e.g. Django code including settings, templates and
statics - are located into grAPES/
.
Two environments are defined - either for requirements and settings:
development
: for local application development and testing. It uses a SQLite3 database and enable debugging by default, add some useful settings and applications for development purpose - i.e. thedjango-debug-toolbar
.production
: for production. It checks that configuration is set and correct, try to optimize performances and enforce some settings - i.e. HTTPS related ones.
Local changes
You can override and extend statics and templates locally. This can be useful
if you have to change the logo for a specific instance for example. For that,
just put your files under the local/static/
and local/templates/
folders.
Regarding the statics, do not forget to collect them after that. Note also that
the local/
folder is ignored by git.
Variable content
All the variable content - e.g. user-uploaded media, collected statics - are
stored inside the var/
folder. It is also ignored by git as it's specific
to each application installation.
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.
Development
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 servermake test
: test the whole applicationmake lint
: check the Python code syntax
Release
Before releasing one should verify that make test
and make lint
are ok.
Migrations should also have been added during development process.
Hygienic checklist
make test
make lint
make check-migrations
git grep '\<print\s*(\|pdb\>\|\<set_trace\>' '*.py'
Release gitmnastic
-
Define variables
export VERSION="x.y.z" # version to be released export ORIGIN="origin" # remote name for pushing my origin export UPSTREAM="cliss21" # remote name for pushing upstream export GITEA_USER="jdoe" # my forge username
-
Fork from the develop branch:
git checkout -b release_$VERSION
-
Build and commit statics
npm run build git add -f grAPES/static package-lock.json git commit -m "build($VERSION): ajoute les statics compilés"
-
Update
grAPES/__init__.py
and complete changelog via:make release
-
Edit and commit it
/usr/bin/editor CHANGELOG.md git add grAPES/__init__.py CHANGELOG.md git commit -m "doc(CHANGELOG): publie la v$VERSION"
-
Tag your release commit
git tag v$VERSION
-
Merge it in master
git push --set-upstream $ORIGIN release_$VERSION git push --tags # then open a PR via xdg-open "https://forge.cliss21.org/cliss21/grAPES/compare/master...$GITEA_USER:release_$VERSION" # then get the PR merged git push --tags $UPSTREAM
That's released. Now we prepare repo for a new develop sprint
-
Rebase develop on master
git fetch --all git checkout develop git rebase $UPSTREAM/master
-
Revert statics from develop
git revert $(git rev-list --all --max-count=1 grAPES/static/) git push $ORIGIN # then open a PR or not xdg-open "https://forge.cliss21.org/cliss21/grAPES/compare/develop...$GITEA_USER:develop" # then get the PR merged (or directly push via git push $UPSTREAM)
-
You should be ready for a new develop sprint
git fetch --all
License
🍇️ grAPES is developed by Cliss XXI and licensed under the AGPLv3+.