Allow quick development environment with Gitpod (#295)

This PR introduces the capability of creating a quick development environment of Winter CMS using Gitpod for testing and further development.

See #295 for more information on the instance configuration.

.gitpod.yml

@@ -0,0 +1,36 @@
+image:
+  file: ./.gitpod/Dockerfile
+
+tasks:
+  - init: ./.gitpod/gitpod-init
+    command: ./.gitpod/gitpod-cmd
+
+ports:
+  - port: 1025
+    onOpen: ignore
+  - port: 3306
+    onOpen: ignore
+  - port: 33060
+    onOpen: ignore
+  - port: 8000
+    visibility: public
+    onOpen: ignore
+  - port: 8025
+    onOpen: ignore
+  - port: 9003
+    onOpen: ignore
+
+vscode:
+  extensions:
+    - felixfbecker.php-debug
+    - bmewburn.vscode-intelephense-client
+
+github:
+  prebuilds:
+    master: true
+    branches: false
+    pullRequests: true
+    pullRequestsFromForks: false
+    addCheck: true
+    addComment: false
+    addBadge: true

.gitpod/Dockerfile

@@ -0,0 +1,71 @@
+FROM gitpod/workspace-mysql
+
+# Install XDebug extension
+RUN sudo apt-get update -q \
+  && sudo apt-get install -y \
+    php-dev \
+    golang-go \
+  && sudo pecl install xdebug
+
+# Install Composer 2 (Gitpod comes pre-installed with Composer 1) - borrowed from official Composer Docker image
+ENV COMPOSER_ALLOW_SUPERUSER 1
+ENV COMPOSER_HOME /tmp
+ENV COMPOSER_VERSION 2.1.6
+
+RUN set -eux; \
+  curl \
+    --silent \
+    --fail \
+    --location \
+    --retry 3 \
+    --output /tmp/keys.dev.pub \
+    --url https://raw.githubusercontent.com/composer/composer.github.io/e7f28b7200249f8e5bc912b42837d4598c74153a/snapshots.pub \
+  ; \
+  php -r " \
+    \$signature = '4ac45767e5ec22652f0c1167cbbb8a2b0c708369153e328cad90147dafe50952'; \
+    \$hash = hash('sha256', preg_replace('{\s}', '', file_get_contents('/tmp/keys.dev.pub'))); \
+    if (!hash_equals(\$signature, \$hash)) { \
+      echo 'Integrity check failed, dev public key is either corrupt or worse.' . PHP_EOL; \
+      exit(1); \
+    }" \
+  ; \
+  curl \
+    --silent \
+    --fail \
+    --location \
+    --retry 3 \
+    --output /tmp/keys.tags.pub \
+    --url https://raw.githubusercontent.com/composer/composer.github.io/e7f28b7200249f8e5bc912b42837d4598c74153a/releases.pub \
+  ; \
+  php -r " \
+    \$signature = '57815ba27e54dc317ecc7cc5573090d087719ba68f3bb7234e5d42d084a14642'; \
+    \$hash = hash('sha256', preg_replace('{\s}', '', file_get_contents('/tmp/keys.tags.pub'))); \
+    if (!hash_equals(\$signature, \$hash)) { \
+      echo 'Integrity check failed, tags public key is either corrupt or worse.' . PHP_EOL; \
+      exit(1); \
+    }" \
+  ; \
+  curl \
+    --silent \
+    --fail \
+    --location \
+    --retry 3 \
+    --output /tmp/installer.php \
+    --url https://raw.githubusercontent.com/composer/getcomposer.org/f24b8f860b95b52167f91bbd3e3a7bcafe043038/web/installer \
+  ; \
+  php -r " \
+    \$signature = '756890a4488ce9024fc62c56153228907f1545c228516cbf63f885e036d37e9a59d27d63f46af1d4d07ee0f76181c7d3'; \
+    \$hash = hash('sha384', file_get_contents('/tmp/installer.php')); \
+    if (!hash_equals(\$signature, \$hash)) { \
+      echo 'Integrity check failed, installer is either corrupt or worse.' . PHP_EOL; \
+      exit(1); \
+    }" \
+  ; \
+  sudo php /tmp/installer.php --no-ansi --install-dir=/usr/bin --filename=composer --version=${COMPOSER_VERSION}; \
+  composer --ansi --version --no-interaction; \
+  composer diagnose; \
+  rm -f /tmp/installer.php; \
+  sudo find /tmp -type d -exec chmod -v 1777 {} +
+
+# Configure Xdebug
+RUN sudo bash -c "echo -e '\nzend_extension = /usr/lib/php/20190902/xdebug.so\n\n[XDebug]\nxdebug.mode=debug\nxdebug.start_with_request = 1\nxdebug.client_host = 127.0.0.1\n' >> /etc/php/7.4/cli/php.ini"

.gitpod/README.md

@@ -0,0 +1,53 @@
+# Winter CMS on Gitpod
+
+Winter CMS now supports the [Gitpod.io](https://gitpod.io) service to provide near-instant development and testing environments for Winter CMS.
+
+This service allows you to check out the Winter CMS codebase at any commit, any branch or any pull request and be given a full Visual Studio Code environment that is completely configured and bootstrapped to run Winter CMS immediately.
+
+Each instance contains the following:
+
+- Winter CMS with the [DebugBar plugin](https://github.com/wintercms/wn-debugbar-plugin).
+- VSCode.
+- MySQL 5.7.
+- PHP 7.4 with all required extensions.
+- PHP Xdebug extension.
+- Composer 2.
+- [MailHog service](https://github.com/mailhog/MailHog/) for capturing emails.
+
+To use this service, you will need an account on Gitpod - one can easily be created by using your GitHub login. You will receive 50 hours per month free for use on Gitpod, but can opt to increase your hours (or even get unlimited hours) by [purchasing a higher plan](https://www.gitpod.io/pricing) on Gitpod.
+
+## Creating a Gitpod instance
+
+There are several ways to create a Gitpod instance of Winter CMS:
+
+- Use one of the **Open in Gitpod** button, which will be available in the README of Winter CMS, as well as any pull request submitted to Winter CMS.
+- Install the [Gitpod extension](https://www.gitpod.io/docs/browser-extension#browser-extension) for Chrome or Firefox, which provides a **Gitpod** button in GitHub.
+- Manually create an instance by copying a GitHub address within the Winter CMS repo, and prefixing the address with `https://gitpod.io/#/`
+
+The Gitpod instance may take a minute or two to boot up if it has not been pre-built.
+
+> **Note:** For brevity, Gitpod instances have the initial admin account set to **admin / admin** as the username and password to login. If you intend to share the URL, we recommend you change this password.
+
+## Accessing the services
+
+The Gitpod instance is set-up to boot all necessary services and then provides two web-facing services - the Winter CMS install itself, which is run on port 8000, and MailHog, which is run on port 8025.
+
+You can click the **Ports** section in the status bar of VSCode, which will take you to the available ports, and click on one of these ports to view the actions for the port. The "globe" icon will open up a special URL which will access the service on that port. We automatically load up Winter CMS on boot in a new tab.
+
+### MySQL
+
+By default, MySQL only runs locally within the Gitpod instance, and cannot be connected to from the outside. However, you can use the [Gitpod Local Companion](https://www.gitpod.io/blog/local-app) service to tunnel into the running Gitpod instance and access its services on your own computer.
+
+Install the app for your OS, then run `gitpod-local-companion-[darwin|linux|windows]` to set up the tunneling service. For MySQL, this will make the database available on port 3306 on your computer.
+
+You can then connect to it using any MySQL management program of your choice.
+
+## Config files
+
+By default, the Winter CMS Gitpod instance will use `php artisan winter:env` to create an `.env` file that will contain your config. Because this command rewrites the main config files in the `config` directory, which will appear as changes in Git, we mark these files as "unwatched" in Git so that they are not committed to GitHub.
+
+If you are editing a pull request that does contain config changes that you wish to include in the PR, you can use the `.gitpod/gitpod-show-config` helper script inside your Gitpod instance to make these files appear in the Git changes.
+
+## Debugging
+
+Debugging Winter CMS in Gitpod is super simple - all necessary setup has already been done! You can access the Debugging tab in VSCode and press start on the debugging tool to use breakpoints within your code. Note that Gitpod does impose a time limit on responses from the web server, so you may find that using the debugging will result in timeouts when viewing your Winter CMS instance, however, debugging should still continue without issue.

.gitpod/gitpod-cmd

@@ -0,0 +1,48 @@
+#!/bin/bash
+
+# Create database
+gp await-port 3306 && mysql -e "DROP DATABASE IF EXISTS winter"
+mysql -e "CREATE DATABASE winter"
+
+# Create environment file
+php artisan winter:env
+
+# Hide config file changes from Git
+./.gitpod/gitpod-hide-config
+
+# Exclude Debugbar files from Git
+echo -e "plugins/winter/debugbar\nstorage/debugbar" >> ./.git/info/exclude
+
+# Rewrite configuration
+sed -i "s|APP_URL=.*$|APP_URL=${GITPOD_WORKSPACE_URL}|g" .env
+sed -i "s|APP_URL=https://|APP_URL=https://8000-|g" .env
+sed -i "s|APP_KEY=.*$|APP_KEY=$(cat /dev/urandom | base64 | head -c 32)|g" .env
+sed -i "s|DB_CONNECTION=.*$|DB_CONNECTION=mysql|g" .env
+sed -i "s|DB_HOST=.*$|DB_HOST=127.0.0.1|g" .env
+sed -i "s|DB_PORT=.*$|DB_PORT=3306|g" .env
+sed -i "s|DB_DATABASE=.*$|DB_DATABASE=winter|g" .env
+sed -i "s|DB_USERNAME=.*$|DB_USERNAME=root|g" .env
+sed -i "s|DB_PASSWORD=.*$|DB_PASSWORD=|g" .env
+sed -i "s|MAIL_DRIVER=.*$|MAIL_DRIVER=smtp|g" .env
+sed -i "s|MAIL_HOST=.*$|MAIL_HOST=127.0.0.1|g" .env
+sed -i "s|MAIL_PORT=.*$|MAIL_PORT=1025|g" .env
+sed -i "s|MAIL_ENCRYPTION=.*$|MAIL_ENCRYPTION=null|g" .env
+sed -i "s|MAIL_USERNAME=.*$|MAIL_USERNAME=null|g" .env
+sed -i "s|MAIL_PASSWORD=.*$|MAIL_PASSWORD=null|g" .env
+sed -i "s|'trustedProxies' => null|'trustedProxies' => '*'|g" config/app.php
+
+# Run migrations
+php artisan winter:up
+
+# Set admin password
+php artisan winter:passwd admin admin
+
+# Run Mailhog in background
+/workspace/go/bin/MailHog >/dev/null 2>&1 &
+
+# Serve site
+php artisan serve >/dev/null 2>&1 &
+gp await-port 8000 && gp preview --external $(gp url 8000)
+
+# Open README
+gp open ./.gitpod/README.md

.gitpod/gitpod-hide-config

@@ -0,0 +1,10 @@
+#!/bin/bash
+
+# Hide config file edits from Git changes
+git update-index --skip-worktree config/app.php
+git update-index --skip-worktree config/cache.php
+git update-index --skip-worktree config/cms.php
+git update-index --skip-worktree config/database.php
+git update-index --skip-worktree config/mail.php
+git update-index --skip-worktree config/queue.php
+git update-index --skip-worktree config/session.php

.gitpod/gitpod-init

@@ -0,0 +1,15 @@
+#!/bin/bash
+
+# Install Mailhog
+go get github.com/mailhog/MailHog
+
+# Add Debug Bar plugin
+composer require --no-update "winter/wn-debugbar-plugin" "4.0.0"
+
+# Install Composer dependencies
+composer update --no-progress
+git reset --hard
+
+# Setup VSCode config
+mkdir -p ./.vscode
+cp ./.gitpod/vscode-launch.json ./.vscode/launch.json

.gitpod/gitpod-show-config

@@ -0,0 +1,10 @@
+#!/bin/bash
+
+# Hide config file edits from Git changes
+git update-index --no-skip-worktree config/app.php
+git update-index --no-skip-worktree config/cache.php
+git update-index --no-skip-worktree config/cms.php
+git update-index --no-skip-worktree config/database.php
+git update-index --no-skip-worktree config/mail.php
+git update-index --no-skip-worktree config/queue.php
+git update-index --no-skip-worktree config/session.php

.gitpod/vscode-launch.json

@@ -0,0 +1,14 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Listen for Xdebug",
+            "type": "php",
+            "request": "launch",
+            "port": 9003
+        }
+    ]
+}