From b8e9247d098bb4552e1496ce1c3c9f07977da5f3 Mon Sep 17 00:00:00 2001 From: Remi Caput Date: Wed, 9 Jan 2019 14:01:41 +0100 Subject: [PATCH] Minor reword of install instructions. --- INSTALL.md | 155 +++++++++++++++++++++++++++-------------------------- 1 file changed, 78 insertions(+), 77 deletions(-) diff --git a/INSTALL.md b/INSTALL.md index ca61b16..51586c2 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -24,57 +24,54 @@ on your target server. Following software is required before you can install yAronet on a server using provided Vagrant box: -* Vagrant 2.2.2 or above (not tested with previous versions) - * Make sure you also satisfied Vagrant dependencies (e.g. Oracle VirtualBox) +* Vagrant 2.2.2 or above (not tested with previous versions): + * Make sure you also satisfied Vagrant dependencies (e.g. Oracle VirtualBox). Step by step install instructions: -* Run `vagrant up` from directory `/setup/vm` -* Wait for machine to be ready -* Go to "Configure website" section below +* Run `vagrant up` from directory `/setup/vm`. +* Wait for machine to be ready. + +Vagrant box will take a few minutes for downloading and installing all +requirements and display a success message on console when done. Go to +"Configure website" section below to continue. ### Option 2: install manually on a server Following software is required before you can manually install yAronet on a development server: -* PHP v7.0.1 or above - * php-curl, php-gd, php-mbstring, php-mcrypt, php-mysql & php-xml extensions -* Any compatible HTTP server like Apache or Nginx -* MariaDB/MySQL server v5.6.41 or above (not tested with previous versions) -* Node.js v10.13.0 or above (you can skip this dependency but won't be able to deploy to production) - * imagemin, imagemin-cli, less, less-plugin-clean-css & uglify-js packages -* Optionally a Unix shell (running it through Cygwin is fine) +* PHP v7.0.1 or above: + * php-curl, php-gd, php-mbstring, php-mcrypt, php-mysql & php-xml extensions. +* Any compatible HTTP server like Apache or Nginx. +* MariaDB/MySQL server v5.6.41 or above (not tested with previous versions). +* Node.js v10.13.0 or above (you can skip this dependency but won't be able to deploy to production): + * imagemin, imagemin-cli, less, less-plugin-clean-css & uglify-js packages. +* Optionally a Unix shell (running it through Cygwin is fine). Step by step install instructions: -* Create a new MySQL database and import `/setup/database/schema.sql` to it - * Make sure to have a MySQL user with read/write permissions on this database -* Create a new location in HTTP server e.g. `/yaronet/` and have it point to `/src/` directory - * If you are using Apache you'll generate required `.htaccess` files in next steps - * If you are using another HTTP server you will need extra configuration detailed below -* Run `/src/configure.sh` from your Unix shell -* Or, if you don't have a Unix shell available: - * Retreive file `parser.php` from latest release of [Deval](https://github.com/r3c/deval/releases) and save it to `/setup/module/deval/src/parser.php` - * Copy `/setup/module/amato/src` to `/src/library/amato` (or create a link to it) - * Copy `/setup/module/deval/src` to `/src/library/deval` (or create a link to it) - * Copy `/setup/module/glay/src` to `/src/library/glay` (or create a link to it) - * Copy `/setup/module/losp/src` to `/src/library/losp` (or create a link to it) - * Copy `/setup/module/queros/src` to `/src/library/queros` (or create a link to it) - * Copy `/setup/module/redmap/src` to `/src/library/redmap` (or create a link to it) -* Go to "Configure website" section below - -If you're using Apache HTTP server configuration files (`/src/.htaccess` and -`/src/static/.htaccess`) will automatically be created when running -configuration script during next steps. Do not forget to include them when -deploying website or run configuration script directly from server to generate -them. - -If you are using another HTTP server you will need to configure it so that: - -* Requests to `index.php` and `install.php` are passed to PHP interpreter -* Requests to `/static/*` are replied using corresponding files from `src/static/` directory -* Other requests are forwarded to `index.php`, preserving original path & query +* Create a new MySQL database and import `/setup/database/schema.sql` to it. + * Make sure to have a MySQL user with read/write permissions on this database. +* Create a new location in HTTP server e.g. `/yaronet/` and have it point to `/src/` directory. + * If you are using Apache you'll generate required `.htaccess` files in next steps. + * If you are using another HTTP server you will need extra configuration detailed below. +* If you have a Unix shell and Node.js installed, run `/src/configure.sh`. +* Otherwise if you don't: + * Retreive file `parser.php` from latest release of [Deval](https://github.com/r3c/deval/releases) and save it to `/setup/module/deval/src/parser.php`. + * Copy `/setup/module/amato/src` to `/src/library/amato` (or create a link to it). + * Copy `/setup/module/deval/src` to `/src/library/deval` (or create a link to it). + * Copy `/setup/module/glay/src` to `/src/library/glay` (or create a link to it). + * Copy `/setup/module/losp/src` to `/src/library/losp` (or create a link to it). + * Copy `/setup/module/queros/src` to `/src/library/queros` (or create a link to it). + * Copy `/setup/module/redmap/src` to `/src/library/redmap` (or create a link to it). +* If you're using Apache HTTP server: + * Configuration files (`/src/.htaccess` and `/src/static/.htaccess`) will automatically be created when running configuration script during next steps. + * Do not forget to include them when deploying website or run configuration script directly from server to generate them. +* If you are using another HTTP server you will need to configure it so that: + * Requests to `index.php` and `install.php` are passed to PHP interpreter. + * Requests to `/static/*` are replied using corresponding files from `src/static/` directory. + * Other requests are forwarded to `index.php`, preserving original path & query. Here is a sample Nginx configuration, assuming you're using php7.0-fpm module for serving PHP-generated contents: @@ -82,26 +79,24 @@ for serving PHP-generated contents: ``` # Pass requests to `/index.php` and `/install.php` through php7.0-fpm socket location = /index.php { - fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; - fastcgi_pass unix:/var/run/php/php7.0-fpm.sock; - include fastcgi-php.conf; + # Serve request using PHP + include fastcgi-php.conf; } location = /install.php { - fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; - fastcgi_pass unix:/var/run/php/php7.0-fpm.sock; - include fastcgi-php.conf; + # Serve request using PHP + include fastcgi-php.conf; } # Serve contents from `/static/*` directly location ^~ /static/ { - try_files $uri $uri/ =404; + try_files $uri $uri/ =404; } # Redirect other requests to `/index.php` location ^~ / { - rewrite "^/(.*)$" / break; - return 404; + rewrite "^/(.*)$" / break; + return 404; } ``` @@ -131,26 +126,25 @@ and images minification) but only recommended ones (CSS pre-compilation). ### Option 1: deploy using Creep -* When deploying using Creep, pre-processing of all static files is done automatically - * Make sure option "engine.text.display.use-less" is `false` in `/src/config.php` -* Create Creep configuration files for deployement (only the first time you're deploying) - * Create `/src/.creep.env`, `/src/library/.creep.env` and `./static/.creep.env` files following Creep's documentation - * Three files are needed to take custom deployment configuration into account, see `/src/library/.creep.def` and `/src/static/.creep.def` for details - * File `/src/.creep.env` should delegate deployment to the other two using "cascades" directive - * Execute `creep` from `/src/` directory to trigger deployment - * Use the sample files below to see how your configuration should look like +* When deploying using Creep, pre-processing of all static files is done automatically: + * Make sure option "engine.text.display.use-less" is `false` in `/src/config.php`. +* Create Creep configuration files for deployement: + * Create `/src/.creep.env`, `/src/library/.creep.env` and `./static/.creep.env` files following Creep's documentation. + * Three files are needed to take custom deployment configuration into account, read `/src/library/.creep.def` and `/src/static/.creep.def` for details. + * Use the sample files below to see how your configuration should look like. -Sample file `/src/.creep.env`: +Sample file `/src/.creep.env` (using "cascades" directive to delegate +deployement of `/src/library/` and `/src/static/` sub-directories): ``` { - "default": { - "connection": "ssh://user@host/website.com", - "cascades": { - "library": ["default"], - "static": ["default"] - } - } + "default": { + "connection": "ssh://user@host/website.com", + "cascades": { + "library": ["default"], + "static": ["default"] + } + } } ``` @@ -158,9 +152,9 @@ Sample file `/src/library/.creep.env`: ``` { - "default": { - "connection": "ssh://user@host/website.com/library" - } + "default": { + "connection": "ssh://user@host/website.com/library" + } } ``` @@ -168,14 +162,19 @@ Sample file `/src/static/.creep.env`: ``` { - "default": { - "connection": "ssh://user@host/website.com/static" - } + "default": { + "connection": "ssh://user@host/website.com/static" + } } ``` -* Run `./setup/configure.sh -d` to start deployment (first deployment will take a few minutes due to all static files being pre-processed) -* Go to "Post-deployment actions" section below +After creating environment files you can run `creep` from `/src/` directory to +start deployment. First deployment will trigger an extra prompt and take a few +minutes due to all static files being pre-processed. Next deployments will only +process modified files and should be much faster. + +Wait for deployment to complete and go to "Post-deployment actions" section +below to continue. ### Option 2: deploy manually @@ -185,12 +184,14 @@ The later option has a significant negative impact on performance and should never be used on a production environment. * To use pre-compiled CSS file on deployed version: - * From `/` directory, run `npm install` then `npm run build` - * Make sure option "engine.text.display.use-less" is `false` in `/src/config.php` + * From `/` directory, run `npm install` then `npm run build`. + * Make sure option "engine.text.display.use-less" is `false` in `/src/config.php`. * To use on-the-fly CSS compilation (debug) on deployed version: - * Make sure option "engine.text.display.use-less" is `true` in `/src/config.php` -* Copy all files from `/src/` directory to remote server (including generated ones if you used CSS compilation) -* Go to "Post-deployment actions" section below + * Make sure option "engine.text.display.use-less" is `true` in `/src/config.php`. +* Copy entire `/src/` hierarchy to remote server (including generated files if you used CSS compilation). + +After files are copied, go to "Post-deployment actions" section below to +continue. ### Post-deployment actions