From 294f0f4ff5792cf07c0af2971cf900e480c8bfc5 Mon Sep 17 00:00:00 2001 From: Tyler Sommer Date: Fri, 6 Oct 2017 01:28:29 -0600 Subject: [PATCH] Overhaul README/CONTRIBUTING --- CONTRIBUTING.md | 4 +- README.md | 126 ++++++++++++++++++++++++++++++--- src/Events.php | 2 +- src/Plugin/Actions.php | 2 +- src/Plugin/PluginInterface.php | 2 +- 5 files changed, 123 insertions(+), 13 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3879cba..0cb4648 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -3,7 +3,7 @@ Contributing Guidelines This document outlines the recommended way to contribute to Packages. -> More information can be found in the [project documentation](http://docs.terramarlabs.com/packages/3.1). +> More information can be found in the [project documentation](http://docs.terramarlabs.com/packages/3.2). Getting started --------------- @@ -29,7 +29,7 @@ Other considerations * The master branch contains active development. * Create or a feature branch or don't-- whatever you prefer! -* The project follows PSR-4 and, somewhat loosely, PSR-2. +* The project follows PSR-1, -2, and -4. * Consider writing unit tests for your change. ### And don't be afraid to ask for help! diff --git a/README.md b/README.md index 7545c01..53b5fe6 100644 --- a/README.md +++ b/README.md @@ -11,14 +11,124 @@ Packages automatically registers GitLab and GitHub project webhooks to keep Sati Packages version 3 works on a plugin based system based around source code repositories. Packages can trigger, with each code push, many automated tasks like documentation generation or code analysis. The simple event-based architecture allows easy creation of new automation tasks. -[View the docs online](http://docs.terramarlabs.com/packages/3.1) +[View the docs online](http://docs.terramarlabs.com/packages/3.2). -Docker ------- -To run docker, you can use: +Installation +------------ -`docker-compose run --service-ports web` +Pre-requisites: + * PHP 5.6 or later + * [Composer](https://getcomposer.org) + * Some database platform supported by [Doctrine 2](http://doctrine-project.org) (sqlite works great!) + * [Redis](https://redis.io/) -This will start a new setup in the active console window. To change the port that the server is bound to, -change the line under `ports` in `docker-compose.yml`, `- "127.0.0.1:80:80"`. Please note that you need to connect to -the exact url specified. If you use `127.0.0.1`, you cannot connect using `localhost`. \ No newline at end of file +Download the [latest release](https://github.com/terramar-labs/packages/releases/latest), or clone the repository. + +```bash +git clone git@github.com:terramar-labs/packages.git +``` + +### Install dependencies + +Switch to the project root directory and run `composer install`. + +```bash +cd packages +composer install +``` + +### Edit configuration + +Copy `config.yml.dist` to `config.yml` and edit as appropriate. + +```bash +cp config.yml.dist config.yml +vi config.yml +``` + +### Generate the database schema + +Packages uses Doctrine ORM to auto-generate the database schema for your configured platform. + +```bash +bin/console orm:schema-tool:create +``` + +Running the application +----------------------- + +Start PHP's built-in webserver to run the Packages web application with minimal effort. + +```bash +# Visit http://localhost:8080 to see the landing page. +php -S localhost:8080 -t web +``` + +### Start a Resque worker + +For fully-automatic integration with GitHub, GitLab, and your Satis repository, you must always have at least one Resque worker running. + +```bash +bin/console resque:worker:start +``` + +> For more information on Resque workers, check [the dedicated section](http://docs.terramarlabs.com/packages/3.2/managing-packages/resque). + + +Using the application +--------------------- + +Read the [usage and design documentation](http://docs.terramarlabs.com/packages/3.2/getting-started/usage) for an overview of Packages functionality. + + +### Development/debug mode + +Visit `index_dev.php` in your browser to view the site with the `dev` environment configuration. In this env, views and the service container are not cached, so changes made are immediately visible. + +### Customizing + +Check out the [Contributing Guide](CONTRIBUTING.md) for the recommended way to set up your development environment. + +Some tips: + +* Views are written using Twig and stored in `views/`. + * Views are cached in `prod` env; use `http://localhost:8080/index_dev.php` to develop. + * All pages inherit from `views/base.html.twig`, except for + * Public landing page views inherit from `views/Default/base.html.twig`. +* [Composer Components](http://robloach.github.io/component-installer/) are used to manage front-end dependencies. The respective `web/images/`, `web/js/bootstrap.min.js`, and such are symlinks pointing to the real files installed by Composer in `vendor/`. +* Check [the documentation](http://docs.terramarlabs.com/packages/3.2/getting-started/customizing) for additional information. + + +Docker support +-------------- + +Packages comes with an example `docker-compose.yml` that sets up the necessary web and Redis server, along with the option to create a self-hosted GitLab with a Highly-Available Redis configuration. + +Visit [the documentation](http://docs.terramarlabs.com/packages/3.2/getting-started/docker) to get started. + +Troubleshooting +--------------- + +1. `index_dev.php` contains a non-localhost block, comment it out when using Docker. +2. Manage Resque and Satis using the `bin/console` command-line utility. + * **Build the Satis `packages.json` file** with the `satis:build` command. + ```bash + bin/console satis:build + ``` + * **View queued Resque jobs in Redis** with the `resque:queue:list` command. + ```bash + bin/console resque:queue:list + ``` + * **View active Resque workers** with the `resque:worker:list` command. + ```bash + bin/console resque:worker:list + ``` + * **Start a Resque worker** with `resque:worker:start`. + ```bash + bin/console resque:worker:start + ``` +3. Check the Resque logs to see if Resque is working properly. + ```bash + tail -f logs/resque.log + ``` + \ No newline at end of file diff --git a/src/Events.php b/src/Events.php index 6c7e2e4..f845a70 100644 --- a/src/Events.php +++ b/src/Events.php @@ -12,7 +12,7 @@ /** * Events defines constants describing the possible events to subscribe to. * - * @see http://docs.terramarlabs.com/packages/3.1/plugins/event-reference + * @see http://docs.terramarlabs.com/packages/3.2/plugins/event-reference */ final class Events { diff --git a/src/Plugin/Actions.php b/src/Plugin/Actions.php index 6808f8f..dd0cabb 100644 --- a/src/Plugin/Actions.php +++ b/src/Plugin/Actions.php @@ -12,7 +12,7 @@ /** * Actions defines constants for the various actions available to plugins. * - * @see http://docs.terramarlabs.com/packages/3.1/plugins/action-reference + * @see http://docs.terramarlabs.com/packages/3.2/plugins/action-reference */ final class Actions { diff --git a/src/Plugin/PluginInterface.php b/src/Plugin/PluginInterface.php index f55163c..c9f8022 100644 --- a/src/Plugin/PluginInterface.php +++ b/src/Plugin/PluginInterface.php @@ -14,7 +14,7 @@ /** * PluginInterface defines the implementation of a Packages plugin. * - * @see http://docs.terramarlabs.com/packages/3.1/plugins/creating-a-plugin + * @see http://docs.terramarlabs.com/packages/3.2/plugins/creating-a-plugin */ interface PluginInterface {