Commit e5288ea1 authored by Karamel's avatar Karamel

Update README.md with installation steps.

parent cdbcca9f
# Pasteque Server
> https://www.pasteque.org
Presentation
============
Pasteque Server is a POS (point of sale) project under the [GNU General Public License v3][gnu].
It is made in [PHP] with [PDO], [MySQL] and [PostgreSQL]
## Presentation
Installation
============
Pasteque API is a POS (point of sale) project under the [GNU General Public License v3][gnu].
It is made in [PHP] with [PDO], [MySQL] and [PostgreSQL]. It is the backbone of the Pasteque suite.
The installation procedure is not complete yet and requires a lot of manual tweaks.
## Installation
First install dependencies with composer.
Then copy `/config/config-sample.ini` to `config/config.ini` and edit it to your liking.
### Prerequisites
Please install the following packages (for a Debian 9 based system)
PHP: `php7.0 php7.0-cli php7.0-gd php7.0-intl php7.0-xml php7.0-mbstring php7.0-zip`
With Apache: `apache2 libapache2-mod-php7.0`
With Postgresql (recommended): `postgresql postgresql-client php7.0-pgsql`, you will require to set `md5` authentication for pasteque users instead of `peer`
With MariaDB (MySQL, slower): `mariadb-server-10.1 mariadb-client-10.1 php7.0-mysql`
### From a release package
Download a release package from https://downloads.pasteque.org/api/ or any other reliable source. These packages has all static files already generated to ease the installation process a little.
Just uncompress the archive and go to `Configuration` below.
### From source
Clone the repository to access to the source files. The repository doesn't embed generated files and requires more steps to intall a development instance.
First install dependencies with composer.
Install a database with Doctrine. Put the following file in the root directory and name it `cli-config.php`
......@@ -36,21 +54,40 @@ Use `php vendor/bin/doctrine orm:schema-tool:update --force` to install the data
Generate proxies with `php vendor/bin/doctrine orm:generate-proxies` then make the directory `src/generated` writeable by your web server user.
Make your web server point to `/src/http/public` and for apache, put the following `.htaccess` in `/src/http/public` and make sure `AllowOverride All` is set for the directory.
### Configuration
```
RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^ index.php [QSA,L]
```
Once all the files are installed, copy `/config/config-sample.ini` to `config/config.ini` and edit it to your liking.
For a single-user instance, you can edit all the `ident/single/*` and `database/single/*`entries to your liking.
For a shared instance, switch `core_ident` and `core_database` to `inifile`. The ini files shares the same structure as the previous entries, without the prefixes ident/single and database/single (i.e. only password= and type=, host= etc).
Also set `jwt_secret` to some random string.
Make sure the web server user can read the config file and the user ini files.
#### Database initialization
To initialize the database, use the sql scripts in `res/database/<type>/schema.sql`. The default data required for a running instance are not yet included, you can find a script at https://downloads.pasteque.org/api/scripts/
#### Web server configuration
Make your web server point to `/src/http/public` and for apache. Make sure `AllowOverride All` is set for this directory for the `.htaccess` in there to work.
You should now call an API: `http(s)://<url_to_pasteque>/api/<route>`
Check your installation by requesting `http(s)://<url_to_pasteque>/fiscal/` you should be prompted to login, and you should be able to log if the user and database are correctly set.
### Install clients
Once the API is up and running, all is required now is some clients to connect to it. Pick a cash register client (Desktop or Android) and a backoffice client (admin or jsadmin) and you are ready to go.
You can now call an API: `http(s)://<domain>/index.php/api/<route>`
## Contributing
Software architecture
=====================
### Software architecture
```
/bin Some php cli scripts to manage your instance.
/config All the ini files, copy and edit the samples to configure your server.
/res Business data, like default data and database schemes.
/src The code of Pasteque server.
......@@ -61,8 +98,7 @@ Software architecture
/vendor Third party libraries. Use composer to install them.
```
Internal code
-------------
### Internal code
Relative to /src/lib
......@@ -76,8 +112,7 @@ Relative to /src/lib
AppContext Read from the config file to run the server from external code.
```
External code
-------------
### External code
Relative to /src/http.
......@@ -91,11 +126,9 @@ All routes are documented with Swagger. They are called through a given URL whic
Routes then make a internal call and transform the response back to HTTP. The routes must be all defined explicitely and annotated for Swagger to be able to generate the documentation.
How do I
========
### How do I
Call an API from the external layer
-----------------------------------
#### Call an API from the external layer
An API call is made from \Pasteque\Server\System\API\APICaller::run. It takes the application context, the class name, the method name and arguments as parameters.
......@@ -108,13 +141,11 @@ The API name is case insensitive and the suffix "API" from the class name can be
It will return a \Pasteque\Server\System\API\APIResult with it's status and object content. To pass the content to the outside, use $response->getStructContent() or $response->toJson() to obtain raw data and not DAO-proxied objects.
Call an API from outside
------------------------
#### Call an API from outside
Look at the documentation for the URL to provide to the server. Authenticate with the login api and pass the fetched token for further calls. The HTTP layer put the token in a cookie to ease access. You can also use GET, POST or HTTP header to pass it.
Create an API
-------------
#### Create an API
Add a new class which name ends by "API" and must have only the first letter capitalized into /src/lib/API, set the desired methods public and that's it. The API layer will magically map your code, do the parameters binding and format the response from and for the external layer.
......@@ -122,15 +153,13 @@ The API classes takes a DAO object from constructor (see /src/lib/System/DAO/DAO
The method opened to the outside must then be mapped by a route un Slim.
Edit a model
------------
#### Edit a model
The models inside /src/lib/Model has annotations for Swagger and Doctrine. When editing a model, the fields will be automatically mapped by the DAO. Doctrine requires to declare attributes protected and add a getter and a setter. You will also have to list the primitive-typed fields and reference fields from both static methods getDirectFieldNames and getAssociationFieldNames. This is required to generate raw data output for the external layer because Doctrine uses proxies for each model attribute.
If the editions have an impact on the behaviour of the API, you will require to edit the corresponding API in /src/lib/API. Otherwise it will be automatically passed to the output and can be searchable without any further edit.
Add internal features
---------------------
#### Add internal features
For all the things relative to the database, see /src/lib/System/DAO: DAO.php for the general interface and DoctrineDAO.php for the implementation. The actual DAO instance is provided by DAOFactory to the API layer.
......@@ -138,8 +167,7 @@ The database access is provided by a system module. See /src/lib/System/SysModul
The AppContext will glue all these tools to pass them afterward to the API. Given an ini configuration file, it will fetch the corresponding system modules and DAO.
Swagger and OAS
===============
### Swagger and OAS
We use Open API Specification (OAS, see <https://www.openapis.org/>) and <http://swagger.io> tools to generate the API documentation.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment