Merge branch 'release/1.3.5'

chrisnharvey · Jun 19, 2020 · a7868ac · a7868ac
2 parents df27b24 + ef9f7ea
commit a7868ac
Show file tree

Hide file tree

Showing 9 changed files with 227 additions and 73 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,7 +2,11 @@
 
 ## [Unreleased](https://github.com/chrisnharvey/magicLAMP/compare/master...develop)
 
-## 1.3.4
+## v1.3.5
+
+- Documentation and readme updates
+
+## v1.3.4
 
 ### Fixed
 

diff --git a/README.md b/README.md
@@ -26,53 +26,26 @@ magicLAMP is a full PHP development environment that works like magic! ✨
 - 🐇 Built-in **RabbitMQ** with management GUI
 - ✅ **So much more**
 
-## Install
+## Getting Started
 
-```
-git clone https://github.com/chrisnharvey/magicLAMP
-cd magicLAMP
-cp .env.example .env
-```
+magicLAMP has extensive [documentation](https://magiclamp.app) to help you get started.
 
-Now modify the ```.env``` file to suit your needs.
+- [Installing magicLAMP](https://magiclamp.app/en/stable/getting-started/installing-magiclamp)
+- [Updating magicLAMP](https://magiclamp.app/en/stable/getting-started/updating-magiclamp)
+- [Quick Start](https://magiclamp.app/en/stable/getting-started/quick-start)
 
-```
-docker-compose pull
-docker-compose up -d
-```
+## Contributing
 
-## Updates
+Thank you for considering contributing to magicLAMP! The contribution guide can be found in [CONTRIBUTING.md](CONTRIBUTING.md).
 
-```
-cd magicLAMP
-git pull
-docker-compose pull
-docker-compose up -d
-```
+## Code of Conduct
 
-## DNS records
+In order to ensure that the magicLAMP project is welcoming to all, please review and abide by the [Code of Conduct](CODE_OF_CONDUCT.md).
 
-The following DNS records are resolved automatically:
+## Security Vulnerabilities
 
-- redis.localhost
-- mysql.localhost
-- elasticsearch.localhost
-- rabbitmq.localhost
-- memcached.localhost
-- phpmyadmin.localhost
-- postgres.localhost
-- pgadmin.localhost
-- mailcatcher.localhost
-- chrome.localhost
-- firefox.localhost
+If you discover a security vulnerability within magicLAMP, please **do not** report it publicly. Instead, please see the [Security Policy](SECURITY.md)
 
-Your projects will be automatically resolved to their respective PHP version as follows:
+## License
 
-| URL                      | PHP Verson | Root Directory                  |
-| ------------------------ | ---------- | ------------------------------- |
-| projectname.56.localhost | 5.6        | PROJECTS_DIR/projectname/public |
-| projectname.70.localhost | 7.0        | PROJECTS_DIR/projectname/public |
-| projectname.71.localhost | 7.1        | PROJECTS_DIR/projectname/public |
-| projectname.72.localhost | 7.2        | PROJECTS_DIR/projectname/public |
-| projectname.73.localhost | 7.3        | PROJECTS_DIR/projectname/public |
-| projectname.74.localhost | 7.4        | PROJECTS_DIR/projectname/public |
+magicLAMP is open-source software licensed under the [MIT license](LICENSE.md).
diff --git a/docs/getting-started/installing-magiclamp.md b/docs/getting-started/installing-magiclamp.md
@@ -0,0 +1,56 @@
+# Installing magicLAMP
+
+!!! note "Installing on Windows"
+    For performance reasons, we recommend using WSL2 on Windows hosts with Ubuntu 20.04 installed
+    Docker Desktop with WSL2 enabled. All `docker` and `docker-compose` commands should be run inside
+    Ubuntu 20.04 in WSL. You will be able to access a bash shell for Ubuntu 20.04 from the Windows
+    start menu.
+
+Installing magicLAMP is easy.
+
+### Step 1
+
+Run the following commands on your host system.
+
+```
+git clone https://github.com/chrisnharvey/magicLAMP
+cd magicLAMP
+cp .env.example .env
+```
+
+### Step 2
+
+Now modify the .env file to suit your needs.
+
+`.env` already provides sane defaults, but you may want to change these to suit
+your needs.
+
+!!! note "Windows Users"
+    For Windows users, we recommend storing your projects directory inside WSL2.
+
+    [See here](https://magiclamp.app/en/stable/troubleshooting/performance-on-windows) for more information.
+
+### Step 3
+
+Run the following commands to pull down the containers and start them:
+
+```
+docker-compose pull
+docker-compose up -d
+```
+
+### Step 4 (optional)
+
+To take full advantage of magicLAMP, you may want to use [Automatic DNS](/automatic-dns)
+and [Automatic SSL](https://magiclamp.app/en/stable/automatic-ssl).
+
+See their respective documentation for information on how to set them up.
+
+### You're done
+
+If you have [Automatic DNS](https://magiclamp.app/en/stable/automatic-dns) setup, you can now visit any of your projects
+using any PHP version by visiting `<project-name>.<php-version>.localhost` in your browser
+(e.g. `my-awesome-project.74.localhost`)
+
+You can also access the [magicLAMP shell](https://magiclamp.app/en/stable/workspace) which by typing `./shell.sh`
+(or `.\shell.cmd` on Windows).
diff --git a/docs/getting-started/quick-start.md b/docs/getting-started/quick-start.md
@@ -0,0 +1,59 @@
+# Quick Start
+
+Now you have successfully installed magicLAMP, here are some quick tips on getting started.
+
+## Accessing your projects
+
+Your projects will be automatically resolved to their respective PHP version as follows:
+
+| URL                      | PHP Verson | Root Directory                  |
+| ------------------------ | ---------- | ------------------------------- |
+| projectname.56.localhost | 5.6        | PROJECTS_DIR/projectname/public |
+| projectname.70.localhost | 7.0        | PROJECTS_DIR/projectname/public |
+| projectname.71.localhost | 7.1        | PROJECTS_DIR/projectname/public |
+| projectname.72.localhost | 7.2        | PROJECTS_DIR/projectname/public |
+| projectname.73.localhost | 7.3        | PROJECTS_DIR/projectname/public |
+| projectname.74.localhost | 7.4        | PROJECTS_DIR/projectname/public |
+
+## Accessing services
+
+The following DNS records are resolved to their respective service automatically:
+
+- redis.localhost
+- mysql.localhost
+- elasticsearch.localhost
+- rabbitmq.localhost
+- memcached.localhost
+- phpmyadmin.localhost
+- postgres.localhost
+- pgadmin.localhost
+- mailcatcher.localhost
+- chrome.localhost
+- firefox.localhost
+
+## Accessing the workspace
+
+You can access the workspace by running `./shell.sh` on Linux and macOS, or `.\shell.cmd` on Windows.
+
+When starting the shell, you will automatically end up in your projects directory.
+
+## Switching PHP version in the workspace
+
+Switching PHP versions in the workspace is easy.
+
+### For a single command
+
+Simply prefix your command with the PHP version you would like to use.
+
+```
+7.4 composer install
+```
+
+### For your entire shell session
+
+If you're going to be working with a specific PHP version in the workspace, instead of
+prefixing every command with the PHP version, run `. <php-version>`
+
+```
+. 7.4
+```
diff --git a/docs/installation-and-upgrading/upgrading.md → docs/getting-started/updating-magiclamp.md b/docs/installation-and-upgrading/upgrading.md → docs/getting-started/updating-magiclamp.md
@@ -1,6 +1,6 @@
-# Upgrading
+# Updating magicLAMP
 
-Upgrading magicLAMP is pretty straight forward. In the magicLAMP directory,
+Updating magicLAMP is pretty straight forward. In the magicLAMP directory,
 pull the latest from GitHub, followed by ```docker-compose pull``` and ```docker-compose up```
 
 ```

diff --git a/docs/index.md b/docs/index.md
@@ -4,7 +4,7 @@
 <a href="https://github.com/chrisnharvey/magicLAMP/actions"><img src="https://img.shields.io/github/workflow/status/chrisnharvey/magicLAMP/Build/master" alt="Build status"></a>
 <a href="http://magiclamp.app/en/stable/?badge=stable"><img src="https://readthedocs.org/projects/magiclamp/badge/?version=stable" alt="Documentation Status"></a>
 <a href="https://twitter.com/chrisnharvey"><img src="http://img.shields.io/badge/author-@chrisnharvey-blue.svg?style=square" alt="Author"></a>
-<a href="https://twitter.com/chrisnharvey"><img src="https://img.shields.io/github/v/release/chrisnharvey/magicLAMP" alt="Latest version"></a>
+<a href="https://github.com/chrisnharvey/magicLAMP/releases"><img src="https://img.shields.io/github/v/release/chrisnharvey/magicLAMP" alt="Latest version"></a>
 <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-brightgreen.svg?style=square" alt="License"></a>
 </p>
 

diff --git a/docs/installation-and-upgrading/installation.md b/docs/installation-and-upgrading/installation.md
diff --git a/docs/troubleshooting/performance-on-windows.md b/docs/troubleshooting/performance-on-windows.md
@@ -0,0 +1,80 @@
+# Performance on Windows
+
+Depending on your setup, you may experience performance issues when using magicLAMP on Windows.
+This is usually caused by mounting your `PROJECTS_DIR` from your Windows host instead of through
+the Linux VM that is included in WSL2.
+
+To resolve this issue, you need to keep your projects directory inside of WSL2 and not on your host system.
+
+## Storing projects in WSL2
+
+!!! note
+    After following this guide, all `docker` and `docker-compose` commands
+    must be run inside of Ubuntu 20.04.
+
+    This is to ensure your projects directory is correctly mounted.
+
+### Prerequisites
+
+- WSL2 installed and enabled in Docker Desktop
+- WSL2 version of Ubuntu 20.04 installed from Microsoft Store
+
+### Creating the projects directory
+
+Open "Ubuntu 20.04" from the start menu in Windows. This will give you a bash shell
+inside of Ubuntu 20.04.
+
+Once you're in here, run the following commands.
+
+```
+sudo mkdir /projects
+sudo chown -R 1000:1000 /projects
+```
+
+### Accessing Linux files in Windows
+
+You can access the files in your WSL2 distro using the Windows File Explorer.
+Depending on how up-to-date your version of Windows is, these will either show up
+under a "Linux" heading in the sidebar, or you can get to them manually by typing
+`\\wsl$` in the file path of Windows Explorer.
+
+Once you can see the network shares, you will need to enter the Ubuntu-20.04 share to
+access the filesystem of Ubuntu 20.04. In here, you should see the `projects` folder you
+just created.
+
+![WSL2 Network Share](https://res.cloudinary.com/chrisnharvey/image/upload/v1592596006/wsl2_lxygj8.png)
+
+If you already have your project files stored in a previous location, you can copy them into this folder.
+
+### Update .env
+
+You now need to update your `.env` file to point `PROJECTS_DIR` to your projects
+folder that is now stored in WSL2.
+
+Based on the previous step, your projects will now be stored in `/projects`, so update
+your the `PROJECTS_DIR` variable in `.env` to match.
+
+```
+PROJECTS_DIR=/projects
+```
+
+### Restart magicLAMP
+
+You now need to restart magicLAMP for these changes to take effect.
+
+You must now run all `docker` and `docker-compose` commands inside of Ubuntu 20.04.
+
+`cd` into the path where you installed magicLAMP. Windows drives can be found in `/mnt`
+(e.g. `/mnt/c/Users/Chris/magicLAMP`).
+
+```
+docker-compose down
+docker-compose up -d
+```
+
+## Working on projects stored in WSL2
+
+Now that your projects are stored inside WSL2, you will need to work on these from the WSL2
+network share.
+
+You should be able to import your projects from this network share into your preferred IDE.
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -14,6 +14,9 @@ repo_url: 'https://github.com/chrisnharvey/magicLAMP'
 
 copyright: 'Copyright &copy; Chris Harvey'
 
+markdown_extensions:
+  - admonition
+
 extra_css:
   - _styles/styles.css
 
@@ -30,9 +33,10 @@ extra:
 nav:
   - index.md
 
-  - Installation and Upgrading:
-      - installation-and-upgrading/installation.md
-      - installation-and-upgrading/upgrading.md
+  - Getting Started:
+      - getting-started/installing-magiclamp.md
+      - getting-started/updating-magiclamp.md
+      - getting-started/quick-start.md
 
   - Workspace:
     - Introduction: workspace/index.md
@@ -68,4 +72,7 @@ nav:
     - ide-integration/vscode.md
 
   - Extending magicLAMP:
-    - extending-magiclamp/docker-compose-overrides.md
+    - extending-magiclamp/docker-compose-overrides.md
+
+  - Troubleshooting:
+    - troubleshooting/performance-on-windows.md