README

VA - VOID

Vortex Adventues - Vortex Online Incharacter Database

Install

Download Composer or update composer self-update.

Clone the repository
Run composer install
If this didn't create the config/app.php (or set folder permissions), then run this command again.
Run ./bin/cake admin checks
- Fix everything it reports as NOT ok (the red lines).
- This mostly consists of reading and editing config/app.php.
- There you need to setup the 'Datasources' and any other configuration relevant for your site.
- The database tables can be created with Migrations ./bin/cake migrations migrate

Configure apache to serve the webroot folder.
Example apache vhost.conf:

<VirtualHost *:80>
    ServerName api.your.domain
    DocumentRoot /var/www/void/webroot

    <Directory />
        Options FollowSymLinks
        AllowOverride None
    </Directory>
    <Directory /var/www/>
        Options Indexes FollowSymLinks MultiViews
        AllowOverride All
        Order allow,deny
        allow from all
    </Directory>

    CustomLog ${APACHE_LOG_DIR}/access.void.log combined
</VirtualHost>

Browse to /admin/checks
- Again, fix everything it reports as NOT ok.
Optionally: load some initial database content with ./bin/cake migrations seed

Update

./bin/cake backup export
- Make a backup of your data.
git pull
- Retrieves the latest code
composer update
- Installs/updates package dependencies.
- This is required if composer.json was modified, otherwise it is still recommended.
./bin/cake migrations migrate
- Updates the database table structure(s).
./bin/cake backup export
- Optionaly: create a backup before resuming regular usage/operations.

Database backups

Database backups can be listed, exported and imported using the CLI.

./bin/cake backup lists all the database backups present.
./bin/cake backup export [description] will created a new backup file.
./bin/cake backup import <file> Import a backup (or any other) sql file.

This tool uses the commandline mysql and mysqldump commands internally.
The created backup files are stored in the backups/ folder.

Warning: old backups might not be compatible with newer tables structures. It is possible to use cake migrations to revert to an earlier database structure. Don't forget to save your data / make a backup before doing this!

Social provider login

Call the /auth/social api endpoint to get the list of all supported social login providers. For each provider the result contains a url and authUri link. Both need to be customized by the front-end before they can be used.

First in the authUri replace the STATE and CALLBACK strings:
- STATE should be a random string used to prevent cross-site request forgery
- CALLBACK is the front-end url where the user gets redirect to after login
Now redirect the user to this modified authUri to start the login proces.
On succesful login the user gets redirected to the CALLBACK location.
Check that the returned state query parameter matches with the earlier provided STATE value.
In the url of the social provider replace CODE and CALLBACK:
- CODE with the code string we got in the query parameter after the login
- CALLBACK must be the same as used in the authUri
Perform a GET on the modified url. This should yield the same result as a regular user+name password. The result contains a JWT that can be used for all following interactions with the void api. Similar, a failed login will result in a 401 error response.

sequenceDiagram
    participant B as Browser
    participant C as Client App
    participant A as VOID Api
    participant P as Provider

B-)+C: get login page
activate B
C-)+A: (0) HTTP GET /auth/social
A--)-C: list of providers, each with "authUri" and "url"
C->>C: (1) replace STATE and CALLBACK in "authUri"
C--)-B: login page
B->>B: user selects login provider
B-)+P: (2) redirect to modified "authUri"
P--)B: login page
B-)P: user authenticates
P--)-B: (3) redirect to CALLBACK with CODE and STATE
B-)+C: 
C->>C: (4) check STATE is unmodified
C->>C: (5) replace CODE and CALLBACK in "url"
C-)+A: (6) GET "url"
A-)+P: verify CODE
P-)-A: user information
A->>A: find player plin
A--)-C: provide JWT
Note over C,A: use JWT to access VOID Api as user
C-)+A: GET /players/<plin>
A--)-C: 
C--)-B: ...
deactivate B

pwerken / va-void

Maintainers

Details