Skip to content

Commit

Permalink
Minor reword of install instructions.
Browse files Browse the repository at this point in the history
  • Loading branch information
@r3c
r3c committed Jan 9, 2019
1 parent 3bbffbf commit b8e9247
Showing 1 changed file with 78 additions and 77 deletions.
155 changes: 78 additions & 77 deletions INSTALL.md
View file
Expand Up @@ -24,84 +24,79 @@ 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:

```
# 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;
}
```

Expand Down Expand Up @@ -131,51 +126,55 @@ 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"]
}
}
}
```

Sample file `/src/library/.creep.env`:

```
{
"default": {
"connection": "ssh://user@host/website.com/library"
}
"default": {
"connection": "ssh://user@host/website.com/library"
}
}
```

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

Expand All @@ -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

Expand Down

0 comments on commit b8e9247

Please sign in to comment.