diff --git a/CHANGELOG.md b/CHANGELOG.md index f8418c3..7ddd0c7 100644 --- 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 index 60f8ec2..5c0e38e 100644 --- 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 new file mode 100644 index 0000000..e0584e9 --- /dev/null +++ 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 `..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). \ No newline at end of file diff --git a/docs/getting-started/quick-start.md b/docs/getting-started/quick-start.md new file mode 100644 index 0000000..cd38667 --- /dev/null +++ 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 `. ` + +``` +. 7.4 +``` \ No newline at end of file diff --git a/docs/installation-and-upgrading/upgrading.md b/docs/getting-started/updating-magiclamp.md similarity index 63% rename from docs/installation-and-upgrading/upgrading.md rename to docs/getting-started/updating-magiclamp.md index 7575467..0084e69 100644 --- a/docs/installation-and-upgrading/upgrading.md +++ b/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 index b5b72ea..f3318f6 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,7 +4,7 @@ Build status Documentation Status Author -Latest version +Latest version License

diff --git a/docs/installation-and-upgrading/installation.md b/docs/installation-and-upgrading/installation.md deleted file mode 100644 index 84b03f5..0000000 --- a/docs/installation-and-upgrading/installation.md +++ /dev/null @@ -1,25 +0,0 @@ -# Installation - -Installing magicLAMP is as 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. - -### Step 3 - -Run the following commands to pull down the containers and start them: - -``` -docker-compose pull -docker-compose up -d -``` \ No newline at end of file diff --git a/docs/troubleshooting/performance-on-windows.md b/docs/troubleshooting/performance-on-windows.md new file mode 100644 index 0000000..e3c2d65 --- /dev/null +++ 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. \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index c8c7390..6a67ce4 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -14,6 +14,9 @@ repo_url: 'https://github.com/chrisnharvey/magicLAMP' copyright: 'Copyright © 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 \ No newline at end of file + - extending-magiclamp/docker-compose-overrides.md + + - Troubleshooting: + - troubleshooting/performance-on-windows.md \ No newline at end of file