Updates for version 2.3.0

CHANGELOG.md

@@ -8,48 +8,55 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 ## [2.2.0] - 2018-06-02
 
 ### Added
-- Enabled private network settings
-- Added configuration parameters for RSA key and github authentication
-- Added vagrant-hostsupdater to set host's `/etc/hosts` file automatically
+
+    - Enabled private network settings
+    - Added configuration parameters for RSA key and github authentication
+    - Added vagrant-hostsupdater to set host's `/etc/hosts` file automatically
 
 ### Changed
-- Changed php role to setup xdebug properly
-- Changed the order and depedencies for apache and php roles
-- Changed roles include in the playbook to be configurable in
-- Changed `variables.yml` into `default.config.yml` and requires it to be copied
-  into `config.yml` for configuration of devbox
-- Cleaned up `projects` variable
+
+    - Changed php role to setup xdebug properly
+    - Changed the order and depedencies for apache and php roles
+    - Changed roles include in the playbook to be configurable in
+    - Changed `variables.yml` into `default.config.yml` and requires it to be copied into `config.yml` for configuration of devbox
+    - Cleaned up `projects` variable
 
 ### Removed
-- Removed temporarly enabed public network
+
+    - Removed temporarly enabed public network
 
 ## [2.1.0] - 2017-04-08
 
 ### Added
-- New project role to handle project specific configuration
-- Added `php-mbstring`
-- Changed host with new Ansible variable syntax (> 2.0)
-- Splits several YAML files into multiple and adds include statements to
-  individual `main.yml` files.
+
+    - New project role to handle project specific configuration
+    - Added `php-mbstring`
+    - Changed host with new Ansible variable syntax (> 2.0)
+    - Splits several YAML files into multiple and adds include statements to
+    individual `main.yml` files.
 
 ### Removed
-- All configuration regarding projects (vhost and database) now resides with the
-project role.
+
+    - All configuration regarding projects (vhost and database) now resides with the
+    project role.
 
 
 ## [2.0.0] - 2017-04-06
 
 ### Added
-- Split the code into roles to be more manageable
-- Adds CHANGELOG.md
-- Tags release 1.0.0
+
+    - Split the code into roles to be more manageable
+    - Adds CHANGELOG.md
+    - Tags release 1.0.0
 
 ### Change
-- Changes to ansible code syntax to be compatible with Ansible 2.2.1
-- Changes to vagrant code syntax to be compatible with Vagrant 1.9.2
-- Changes to vagrant to use Ubuntu Xenial 16.04
+
+    - Changes to ansible code syntax to be compatible with Ansible 2.2.1
+    - Changes to vagrant code syntax to be compatible with Vagrant 1.9.2
+    - Changes to vagrant to use Ubuntu Xenial 16.04
 
 ## [1.0.0] - 2015-08-24
 
 ### Added
-- First release of code
+
+    - First release of code

README.md

@@ -2,22 +2,19 @@
 
 ## Prerequisites
 
-Devbox is a virtual devevelopment box for PHP and JavaScruipt development
+Devbox is a virtual devevelopment box for PHP and JavaScript development
 (including frameworks like Hugo, Symfony, WordPress and Drupal). Using the LAMP
 stack provided you can start development without worrying about setting up your
 computer as a development environment.
 
 Devbox works with the following software:
 
-  - Vagrant >= 2.1.1
-  - Ansible >= 2.5
-  - VirtualBox
-  - Ubuntu Xenial 16.04
+  - Vagrant >= 2.2.10
+  - Ansible >= 2.9.6
+  - VirtualBox >= 6.1
+  - Ubuntu 20.04.1 LTS (Focal Fossa)
 
-Devbox assumes that projects are developed with Git and requires a valid RSA key
-from the local user which has been added in Github.
-
-## Usage
+## Install
 
 Get devbox in your local machine:
 
@@ -38,69 +35,120 @@ environment:
 vagrant up
 ```
 
-You can login to the devbox with the following command:
+## Basic usage
+
+Login to devbox via SSH:
 
 ```
 vagrant ssh
 ```
 
-Happy coding! See below for configuration parameters.
+For server changes in `config.yml` to take effect (e.g. add a new project) you
+need to reprovision the environment:
+
+```
+vagrant provision
+```
+
+For virtual machine changes in `config.yml` to take effect (e.g. change the IP
+address) you need to reload the configuration:
+
+```
+varnish reload
+```
+
+To access vagrant help:
+
+```
+vagrant help
+```
 
 ## Configuration
 
 The development environment can be customised via the `config.yml` file and the
-variables contained within. 
+variables contained within.
+
+### Configuring the VM
 
-### Configuring a remote user
+The virtual machine can be automatically configured via the variables in
+**Machine** and **Folder mapping**. There are a number of options that allow
+devbox to operate in various conditions.
 
-The `remote_user` variable is used to set the user in the guest machine. The
-default user in Vagrant is ubuntu and is reccomended to be left as is.
+Folder mapping is achieved through NFS and bindfs to ensure that permisions are
+set as expected. By default devbox is using 775 for directories and 644 for
+files but behaviour can be overriden via `vm_folder_perm`.
 
-### Configuring an RSA key
+### Configuring Git, an RSA key and repositories
 
-The `rsa_key` variable accepts as input a path from the host machine which
-should resolve to an rsa key. It is used to authenticate in github and should be
-added there prior to any git related operations in the development server.
+The git configuration section contains variables that control the configuration
+of Git and RSA keys. You can control how your local key is named in devbox so
+you can add your development key indepedently of any other key already set.
+
+The repositories configuration section contains a variable that is used to setup
+the devbox `~/.ssh/config` file. Public key fingerprints can be used to validate
+a connection to a remote server. Devbox automatically adds RSA fingerprints
+in `~/.ssh/known_hosts` for the repositories declared.
 
 ### Configuring the server stack
 
 The `config_roles` variable is used to customise the software stack configured
 in the server. Comment out roles not needed.
 
-### Configuring your projects
+### Configuring projects
 
 Vagrant allows to share directories between the host and the guest
 systems. Devbox takes advantage of that feature to expose local projects which
 can then be served through the LAMP stack.
 
-Devbox expects a `projects` folder to exist in the same contains directory with
-devbox:
-
-```
-.
-├── devbox
-└── projects
-   ├── projectA
-   ├── projectB
-   └── projectC
-```
-
-All directories contained withing projects will be exposed in `~/projects` in
-the guest system.
-
-For each project the following parameters can be set:
-
-- domain (string): The URI to access project.
-- docroot (string) The path of the project in devbox (user `{{ remote_user }}`
-  for indepedence
-- db_user (string): The name of the database user to be used (root will be used
-  if empty)
-- db_pass (string): The passwrd of the database user to be used (root will be used if empty)
-- db_name (string): The database name to be used (if empty database creation is skipped)
-- tech (string): The technology used in the project. Options include:
-    - hugo
-	- drupal
-	- symfony
+Devbox is configurable to act as a standalone server hosting many projects or as
+a development environment within a particular project. In either case it expects
+that the folder containing the project or projects to be declared via
+`projects_path`.
+
+Each project is configured via the `projects` dictionary which accepts the
+following parameters:
+
+  - **domain** (_string_): The URI to access project in the browser. The value is
+  automatically picked up and added to `/etc/hosts`.
+  - **docroot** (_string_) The path of the project in devbox. Can be any
+    location or combined with `projects_path`.
+  - **type** (_string_): The technology used in the project. Options include:
+    empty, hugo, drupal, wordpress, symfony.
+  - **database** (_string_): The database to be used. If empty database creation is skipped
+  - **repo** (_string_): a git path to checkout existing projects (uses path)
+
+### Configuring Xdebug
+Xdebug is enabled by default but you would need to set it up to your IDE. For
+Eclipse you need to do the following:
+
+  1. Add a new server
+  2. Configure the new server with xdebug
+  3. Run the debugger
+
+To setup a server go to `Window > Preferences > PHP > Servers` and add new. It
+will ask for the following:
+
+  - Server tab
+    - Server name: add the individual project name
+	- Base url: the domain configured in project
+	- Document root: the location of the project on your host system
+  - Debbuger tab
+    - Debugger: xdebug
+	- Port: 9000
+
+Next locate a file from your project in PHP Explorer, right click and select
+`Debug as > Debug configurations`. It will ask for the following:
+
+  - Server tab
+    - PHP server: select the one you just created
+	- File: select the project index file
+  - Debuger tab
+    - Ensure XDebug is selected
+	- Enable 'Break At First Line'
+	- Click debug
+
+This will launch a new window and a dialog box will appear informing about the
+debug perspective in Eclipse. Accept and start debugging.
 
 ### Configuring additional software to be added
 
@@ -109,63 +157,12 @@ the main build. It is intended for smaller packages that do not require
 customisation. If more software with significant customisation is needed
 consider to open a pull request.
 
-### Configuring Vagrant
-
-Devbox offers a complete development environment out of the box. Vagrant is
-controled through a `Vagrantfile` bunlded at the root of the repository. Within
-that file there are parameters about:
-
-  - vagrant options about the base image, synchronising folders, network, etc
-  - virtual machine options about memory, etc
-  - provision options about ansible
-
-Please follow through [vagrant documentation](https://www.vagrantup.com/docs/)
-for a more thorough understanding of how it can be tweaked.
-
-## Usage
-
-### Using Vagrant
-
-To connect to the VM use the following:
-
-```
-vagrant ssh
-```
-
-For changes in `config.yml` to take effect use:
-
-```
-vagrant provision
-```
-
-For changes in `Vagrantfile` to take effect vagrant configuration need to be roloaded:
-
-```
-varnish reload
-```
-
-Access help via:
-
-```
-vagrant help
-```
-
-### Accessing projects
-
-Devbox listens to a private network with IP set to 10.10.10.10. Add an entry per
-project in your `/etc/hosts` file:
-
-```
-10.10.10.10    PROJECT_DOMAIN
-```
-
-Then point your browser to the domain in port 8000:
-
-```
-http://PROJECT_DOMAIN
-```
+### Configuring additional tasks to be performed
 
-You should see the homepage of your project.
+The `additional_tasks` variable allows additional tasks to be performed after
+the server has been provisioned. This can be used for some adhoc configuration
+like downloading emacs configuration specific to the user or adding custom
+aliases to `.bashrc`.
 
 ## Contributions