diff --git a/README.md b/README.md index 25907c63..3124cb59 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,21 @@ -Presentator [![Yii2](https://img.shields.io/badge/Powered_by-Yii_Framework-green.svg?style=flat)](http://www.yiiframework.com/) [![Latest Release](https://img.shields.io/github/release/ganigeorgiev/presentator.svg)](https://github.com/ganigeorgiev/presentator/releases) [![Gitter chat](https://badges.gitter.im/presentatorio/presentator.png)](https://gitter.im/presentatorio/presentator) +Presentator v1 [![Yii2](https://img.shields.io/badge/Powered_by-Yii_Framework-green.svg?style=flat)](http://www.yiiframework.com/) [![Gitter chat](https://badges.gitter.im/presentatorio/presentator.png)](https://gitter.im/presentatorio/presentator) ====================================================================== +**IMPORTANT!** + +**Presentator v1 is deprecated and won't receive updates except security fixes.** + +**Please consider upgrading to [Presentator v2](https://github.com/presentator/presentator) by following the [upgrade instructions](https://github.com/presentator/presentator/blob/master/UPGRADE.md).** + +> **Presentator v1 wiki docs are moved to `./wiki` folder.** + +--- + ![img](https://raw.githubusercontent.com/wiki/ganigeorgiev/presentator/images/interface.png) [Presentator](https://presentator.io) is design presentation and collaboration platform. Its main goal is to enable web designers to create simple dynamic prototypes and to speed up the client feedback. -> **IMPORTANT NOTE:** -Presentator is now being redesigned and rewritten from scratch (the code becomes much cleaner by removing the `app` component and using the REST API as primary backend interface + vue/vuex for frontend). -Current version is still maintained, but new functionality will be added to v2 (check [v2.0.0 milestone](https://github.com/ganigeorgiev/presentator/milestone/10) page for some of the already planned enhancements). -The new version will be released ~~mid May/June 2019~~ at the **end of July 2019** (but no hard deadlines). - ## Quick navigation - [Getting started](https://github.com/ganigeorgiev/presentator/wiki) - [Updates](https://github.com/ganigeorgiev/presentator/wiki/Updates) diff --git a/wiki/Home.md b/wiki/Home.md new file mode 100644 index 00000000..43827ac7 --- /dev/null +++ b/wiki/Home.md @@ -0,0 +1,8 @@ +Welcome to **Presentator** - an Open Source design collaboration and presentation platform. + +This wiki is the main source of documentation for users and developers working with (or contributing to) the Presentator project. +Use the wiki sidebar links to navigate within the documention. + +If this is your first time hearing about Presentator, we recommend starting with the [Presentator website](https://presentator.io). + +![Interface](images/interface.png) diff --git a/wiki/_Sidebar.md b/wiki/_Sidebar.md new file mode 100644 index 00000000..8f33a2c5 --- /dev/null +++ b/wiki/_Sidebar.md @@ -0,0 +1,19 @@ +**[Home](Home)** + + +**Getting started** + +- [GUI installer](GUI-installer) +- [Develop with Docker](Develop-with-Docker) +- [Manual installation](Manual-installation) +- [Post installation steps](Post-installation) +- [Updates](Updates) +- [Running tests](Running-tests) + + +**Project structure** + +- [Overview](Overview) +- [Conventions](Conventions) +- [Requirements](Requirements) +- [Configurations and environments](Configurations-and-environments) diff --git a/wiki/images/erd.png b/wiki/images/erd.png new file mode 100644 index 00000000..9dcf607b Binary files /dev/null and b/wiki/images/erd.png differ diff --git a/wiki/images/installer.png b/wiki/images/installer.png new file mode 100644 index 00000000..007dfe50 Binary files /dev/null and b/wiki/images/installer.png differ diff --git a/wiki/images/interface.png b/wiki/images/interface.png new file mode 100644 index 00000000..1c014020 Binary files /dev/null and b/wiki/images/interface.png differ diff --git a/wiki/setup/Develop-with-Docker.md b/wiki/setup/Develop-with-Docker.md new file mode 100644 index 00000000..522d9b97 --- /dev/null +++ b/wiki/setup/Develop-with-Docker.md @@ -0,0 +1,42 @@ +Creating a development environment with Docker is probably one of the easiest way to get started with the project. + +> Make sure that you have installed **[Docker](https://docs.docker.com/install/)** and **[Docker Compose](https://docs.docker.com/compose/install/)**. + +1. Add the following line in your `/etc/hosts` file: + + ``` + 127.0.0.1 adminer.local app.presentator.local api.presentator.local + ``` + +2. Clone or download the [Presentator repository](https://github.com/ganigeorgiev/presentator) and execute the following commands: + + ```bash + # start the docker daemon service (if is not started already) + sudo systemctl start docker + + # navigate to the project root dir + cd /path/to/presentator + + # start the project containers (nginx-proxy, mariadb, adminer and the application itself) + docker-compose up + + # --> open new terminal window in the same working directory... + + # install app dependencies, db migrations, etc. + ./docker/scripts/setup + ``` + +**That's it!** You should be able to access the previously added vhosts in your browser: + +- [adminer.local](http://adminer.local) - light and secure database management GUI tool +- [app.presentator.local](http://app.presentator.local) - the application web interface +- [api.presentator.local](http://api.presentator.local) - the application API + +For easier development, the following helper docker scripts are available: + +- **`./docker/scripts/setup`** - take care for the first-time application setup +- **`./docker/scripts/run`** - execute any commands within the app container, eg. `./docker/scripts/run php yii migrate` +- **`./docker/scripts/grunt`** - run grunt tasks, eg. `./docker/scripts/grunt css` +- **`./docker/scripts/codecept`** - run project tests, eg. `./docker/scripts/codecept unit` + +> Check the project `/path/to/presentator/docker` directory for error logs, `php.ini` directives, mariadb config variables, etc. diff --git a/wiki/setup/GUI-installer.md b/wiki/setup/GUI-installer.md new file mode 100644 index 00000000..0fb96fd2 --- /dev/null +++ b/wiki/setup/GUI-installer.md @@ -0,0 +1,22 @@ +Presentator comes with a small GUI installer. +This type of installation is suitable for production environment. + +1. Create a new database (with `utf8_general_ci` or `utf8_unicode_ci` collation). + +2. Download the latest build from https://presentator.io/downloads/latest and extract it to your server directory. + + > For security reasons, if you are using a shared hosting service it is recommended to extract the archvie files **outside** from your default **public_html(www)** directory! + +3. Setup your domain (or create a new subdomain) and point it to the main application web directory, eg. `/path/to/presentator/app/web`. + + > Optional: if you are intending to make use of the API of the platform, create a subdomain and point it to the api application web directory - `/path/to/presentator/api/web`. + +4. Navigate to `https://my-site.example/install` and follow the instructions of the graphic installer. + + > You may also want to check `https://my-site.example/requirements.php` to ensure that your server meets the minimum requirements. + +![GUI Installer](images/installer.png) + +After the installer completes you should be able to access and start using the platform at `https://my-site.example`. + +> Don't worry, you can always change later the application configurations (db, mailer, etc.) by editting `/path/to/presentator/common/config/main-local.php` and `/path/to/presentator/common/config/params-local.php` diff --git a/wiki/setup/Manual-installation.md b/wiki/setup/Manual-installation.md new file mode 100644 index 00000000..e00269d7 --- /dev/null +++ b/wiki/setup/Manual-installation.md @@ -0,0 +1,48 @@ +Rather than using the [GUI](GUI-installer), you could always install the application manually. +This type of installation is suitable for both production and development setup. + +Before getting started make sure that you have checked the project [requirements](Requirements) and installed [Composer](https://getcomposer.org/). + +1. Clone or download the project repository + + ```bash + git clone https://github.com/ganigeorgiev/presentator.git + ``` + +2. Setup a vhost/server address for the **app**, eg. `http://app.presentator.local/` and point it to `/app/web`. + +3. Setup a vhost/server address for the **api**, eg. `http://api.presentator.local/` and point it to `/api/web`. + +4. Open a console terminal and execute: + + ```bash + # navigate to the project root dir + cd /path/to/presentator + + # install vendor dependencies + composer install + + # execute the init command and select the appropriate environment (dev or prod) + php init + ``` + +5. Create a new database (with `utf8_general_ci` or `utf8_unicode_ci` collation) and adjust the `database` and `mailer` components in `common/config/main-local.php` accordingly. + +6. Adjust the applications required parameters in `common/config/params-local.php`. + +7. Open a console terminal and apply DB migrations. + + ```bash + php /path/to/project/yii migrate + ``` + +**That's it!** You should be able to access the previously defined server addresses in your browser. + + +### Updating app assets + +To be able to autogenerate api doc, change and minify app assets, first you have to install `npm` and then run `npm install`. + +After that you should be able to start [Grunt](http://gruntjs.com/getting-started) with the `grunt` command and just wait all tasks to complete. + +> Check Gruntfile.js for all available tasks and options. diff --git a/wiki/setup/Post-installation.md b/wiki/setup/Post-installation.md new file mode 100644 index 00000000..10a351e5 --- /dev/null +++ b/wiki/setup/Post-installation.md @@ -0,0 +1,36 @@ +### Regular/Super User + +By default all registered users has Regular User access rights (_access to only their own account and projects_). +For easier system administration you can set Super User access rights (_access to all system accounts and projects_) to one or more registered users (**available since v1.7+**). +Change the user's `type` column manually in your DB (_0 - Regular, 1 - Super_) or run one of the following console commands: + +```bash +# sets Super User access +php yii users/super test@example.com + +# sets Regular User access +php yii users/regular test@example.com +``` + + +### Cron Jobs + +To optimize the performance of the service you could schedule the following cron jobs: + +- **Mails Queue processing (v1.3+)** + + First, make sure to enable `useMailQueue` parameter in `common/config/params-local.php` + ```php + return [ + 'useMailQueue' => true, + 'purgeSentMails' => true, // whether to delete successfully processed MailQueue records + // ... + ] + ``` + + Setup your crontab to run the `php yii mails/process` console command, eg.: + ```bash + # process 50 mails at every 5 minutes + */5 * * * * php /path/to/project/yii mails/process 50 + ``` + > Check `console\controllers\MailsController::actionProcess()` for all available command arguments. diff --git a/wiki/setup/Running-tests.md b/wiki/setup/Running-tests.md new file mode 100644 index 00000000..b5f68064 --- /dev/null +++ b/wiki/setup/Running-tests.md @@ -0,0 +1,67 @@ +Presentator uses [Codeception](http://codeception.com/) as its primary test framework. +There are tests for each application component - `app/tests`, `api/tests` and `common/tests`. + +Tests require an additional database, which will be cleaned up between tests. +Create a new database according to config in `common/config/test-local.php` and execute: + +``` +php yii_test migrate +``` + +Build the test suite: +``` +/path/to/project/vendor/bin/codecept build +``` + +Then all applications tests can be started by running: +``` +/path/to/project/vendor/bin/codecept run +``` + + +### App tests +Contains Unit and Functional tests for all `app` application models and actions. +To run only `app` tests, navigate to the `app` dir and execute: +``` +# run unit/integration and functional tests +/path/to/project/vendor/bin/codecept run + +# run only unit/integration tests +/path/to/project/vendor/bin/codecept run unit + +# run only functional tests +/path/to/project/vendor/bin/codecept run functional +``` + + +### Api tests +Contains Unit and REST tests for all `api` application models and actions. +To run only `api` tests, navigate to the `api` dir and execute: +``` +# run unit/integration and functional tests +/path/to/project/vendor/bin/codecept run + +# run only unit/integration tests +/path/to/project/vendor/bin/codecept run unit + +# run only functional tests +/path/to/project/vendor/bin/codecept run functional +``` + + +### Common tests +Mainly Unit tests for all common AR models and classes. +Common fixtures are also located there. +To run only `common` tests, navigate to the `common` dir and execute: +``` +/path/to/project/vendor/bin/codecept run +``` + + +### Useful links + +- [Codeception Unit testing guide](http://codeception.com/docs/05-UnitTests) +- [Codeception Function testing guide](http://codeception.com/docs/04-FunctionalTests) +- [Codeception REST testing guide](http://codeception.com/docs/10-WebServices#REST) +- [Yii Codeception module](http://codeception.com/for/yii) +- [Speed up your tests using MySQL/MariaDB server with tmpfs datadir](https://github.com/martingeorg/tmpfs-mysql) diff --git a/wiki/setup/Updates.md b/wiki/setup/Updates.md new file mode 100644 index 00000000..474a6f87 --- /dev/null +++ b/wiki/setup/Updates.md @@ -0,0 +1,33 @@ +**Before you get started, it's a good idea to backup your database and all Presentator files.** + +> **WARNING**: The update process will affect all core files used to run Presentator. If you have made any modifications to those files, your changes will be lost. + + +### For v1.6.0+ + +Navigate to your project root directory and run the `update` console command: + +```bash +# navigate to project root dir +cd /path/to/presentator + +# run the update console command +php yii update +``` + + +### Before v1.6.0 + +1. Download the latest build from https://presentator.io/downloads/latest. + +2. Extract and replace the archive in your project root directory (don't worry, your `main-local` and `params-local` configurations will be not deleted). + +3. Delete the app installer directory: + + ```bash + rm -rf /path/to/presentator/app/web/install + ``` + +4. Run `php yii migrate/up`. + +For follow-up updates follow the instuctions [For v1.6.0+](#for-v160) diff --git a/wiki/structure/Configurations-and-environments.md b/wiki/structure/Configurations-and-environments.md new file mode 100644 index 00000000..243af96d --- /dev/null +++ b/wiki/structure/Configurations-and-environments.md @@ -0,0 +1,25 @@ +Each environment is represented by a set of files under the `environments` directory. +The `init` command is used to initialize an environment. What it really does is copy everything from the environment directory over to the root directory where all applications are. + +By default there are two environments: `dev` and `prod`. First is for development. It has all the developer tools +and debug turned on. Second is for server deployments. It has debug and developer tools turned off. + +Typically environment contains application bootstrap files such as `index.php` and config files suffixed with `-local.php`. +These are either personal configs of team members which are usually in `dev` environment or configs of specific servers. +For example, production database connection could be in `prod` environment `-local.php` config. These local configs are added to `.gitignore` and never pushed to source code repository. + +In order to avoid duplication, configurations are overriding each other. For example, the `api` reads configuration in the following order: + +- `common/config/main.php` +- `common/config/main-local.php` +- `api/config/main.php` +- `api/config/main-local.php` + +Parameters are read in the following order: + +- `common/config/params.php` +- `common/config/params-local.php` +- `api/config/params.php` +- `api/config/params-local.php` + +Or in other words - **the later config file overrides the former.** diff --git a/wiki/structure/Conventions.md b/wiki/structure/Conventions.md new file mode 100644 index 00000000..2a10cb9a --- /dev/null +++ b/wiki/structure/Conventions.md @@ -0,0 +1,41 @@ +### DB + +![img](images/erd.png) + +The project makes use of the following DB conventions: + +- use InnoDB table engine +- use `utf8_unicode_ci` collation ([difference between general_ci](http://stackoverflow.com/questions/766809/whats-the-difference-between-utf8-general-ci-and-utf8-unicode-ci#answer-766996)) +- add `Rel` suffix to the junction tables +- table names must be in camelCase format (eg. `userProjectRel`) +- table columns must be in camelCase format (eg. `passwordResetToken`) +- Whenever is possible add named foreign keys and indexes (eg. `fk_setting_to_user`) +- each change must be applied via Yii migration tool + +> The camelCased naming is used to be consistent with: +> 1. ActiveRecord DB properties, class properties and relation methods +> 2. ActiveRecord and their related form model properties (eg. `User` and `UserForm`) +> 3. REST API response keys + + +### PHP + +**Each php class must follow the accepted [PSR standards](http://www.php-fig.org/psr/#accepted).** + +In addition: + +- each public method should have a related Unit test (see [Running tests](start-tests.md)). +- each method should have comment block tags based on [phpDocumentor tags](https://phpdoc.org/docs/latest/internals/tags.html) (method description is optional) +- REST API actions must documented following [apiDoc params](http://apidocjs.com/#params) + + +### JS/HTML/SASS + +> coming soon... + + +### Additional notes + +- [Yii 2 Guide](http://www.yiiframework.com/doc-2.0/guide-index.html) +- [Yii 2 Class reference](http://www.yiiframework.com/doc-2.0/index.html) +- [Yii 2 Coding standards](https://github.com/yiisoft/yii2-coding-standards) diff --git a/wiki/structure/Overview.md b/wiki/structure/Overview.md new file mode 100644 index 00000000..c76ae1c4 --- /dev/null +++ b/wiki/structure/Overview.md @@ -0,0 +1,100 @@ +The project has three application components: `api`, `app` and `console`. + +Api is used to implement REST API support. + +App is the main application that handles login, register, user administration and such functionality. + +Console is typically used for cron jobs and low-level server management. Also it's used during application deployment and handles migrations and assets. + +There is also a `common` directory that contains files used by more than one application. For example, `User` model. + +Both `api` and `app` are web applications and both contain the web directory. That's the webroot you should point your web server to. + +Each application has its own namespace and [alias](#project-defined-path-aliases) corresponding to its name (_for the `app` the alias is `@main`_). Same applies to the common directory. + + +### Project structure + +``` +api + config/ contains api configurations + controllers/ contains Web controller classes + models/ contains api-specific model classes + runtime/ contains files generated during runtime + tests/ contains tests for api application + web/ contains the entry script and Web resources +app + assets/ contains application assets such as JavaScript and CSS + config/ contains app configurations + controllers/ contains Web controller classes + models/ contains app-specific model classes + runtime/ contains files generated during runtime + tests/ contains tests for app application + views/ contains view files for the Web application + web/ contains the entry script and Web resources +common + config/ contains shared configurations + mail/ contains view files for e-mails + models/ contains model classes used in both app and api + tests/ contains tests for common classes +console + config/ contains console configurations + controllers/ contains console controllers (commands) + migrations/ contains database migrations + models/ contains console-specific model classes + runtime/ contains files generated during runtime +docker/ contains docker development environment settings and helper scripts +environments/ contains environment-based overrides +*vendor/ contains dependent 3rd-party packages +*node_modules/ contains node js modules like Grunt, node-sass, etc. +``` + +The root directory contains the following subdirectories: + +- `api` - api web application +- `app` - app web application +- `common` - files common to all applications +- `console` - console application +- `environments` - environment configurations + +The root directory contains the following set of files. + +- `.gitignore` - contains a list of directories ignored by git +- `composer.json` - Composer config +- `package.json` - NPM config +- `Gruntfile.js` - Grunt config +- `codeception.yml` - global codeception file to run tests from all apps +- `docker-compose.yml` - docker development application services configurations +- `init` - application initialization script +- `init.bat` - same for Windows +- `LICENSE.md` - project license info +- `README.md` - project doc start point +- `requirements.php` - Yii requirements checker +- *`yii` - console application bootstrap +- *`yii.bat` - same for Windows +- *`yii_test` - test application bootstrap +- *`yii_test.bat` - same for Windows + + +### Project defined path aliases: + +Defined in `common/config/bootstrap.php`. + +- `@console` - console directory +- `@common` - common directory +- `@api` - api web application directory +- `@main` - main web application directory (**NB!** `@app` is reserved) +- `@mainWeb` - main web application directory + + +### Yii 2 default path aliases: + +Defined in the application init constructor. + +- `@yii` - framework directory +- `@app` - base path of currently running application +- `@runtime` - runtime directory of currently running web application +- `@vendor` - Composer vendor directory +- `@bower` - vendor directory that contains the [bower packages](http://bowerio/) +- `@web` - base URL of currently running web application +- `@webroot` - web root directory of currently running web application diff --git a/wiki/structure/Requirements.md b/wiki/structure/Requirements.md new file mode 100644 index 00000000..0c343e09 --- /dev/null +++ b/wiki/structure/Requirements.md @@ -0,0 +1,22 @@ +- Apache HTTP server + + > If you prefer Ngnix you'll need to manually setup redirect rules pointing to `/app/web/index.php` and `api/web/index.php`) + +- _PHP 5.6-7.3_ with the following extensions: + + ``` + Reflection + PCRE + SPL + MBString + OpenSSL + Intl + ICU version + Fileinfo + DOM extensions + GD + ``` + +- DB - _MySQL v5.5+_ or _MariaDb 10+_ (recommended) + +> From the project root directory run the console command `php requirements.php` for more detail check.