From 1f404d1a6494e1f06632eef9bf70b5ee756fc9db Mon Sep 17 00:00:00 2001 From: Ben Thomson Date: Mon, 30 Sep 2024 05:41:38 +0000 Subject: [PATCH] Add introductory README, simplify build --- .devcontainer/README.md | 62 +++++++++++++++++++++++++++++++++ .devcontainer/devcontainer.json | 12 ++++--- 2 files changed, 69 insertions(+), 5 deletions(-) create mode 100644 .devcontainer/README.md diff --git a/.devcontainer/README.md b/.devcontainer/README.md new file mode 100644 index 000000000..38775dc61 --- /dev/null +++ b/.devcontainer/README.md @@ -0,0 +1,62 @@ +# Welcome to the Winter development environment + +

+ Winter CMS Logo +

+ +This development environment container sets up a fully-functional installation of Winter CMS, running on Apache 2 with PHP 8.3, and makes it simple to start working with Winter CMS in VSCode, PHPStorm and online code-editing suites such as GitHub Codespaces. + +If you opted to use the `bootstrap-winter` feature, which is enabled by default, Winter CMS will be automatically configured and an administrator account will be generated with the credentials **admin / admin** for you to quickly sign in. It is recommended once you have done so that you change this password immediately. + +The following plugins and themes will be installed automatically with this feature: + +- Workshop theme (https://github.com/wintercms/wn-workshop-theme) +- Pages plugin (https://github.com/wintercms/wn-pages-plugin) +- Blog plugin (https://github.com/wintercms/wn-blog-plugin) +- Test plugin (https://github.com/wintercms/wn-test-plugin) + +## Using this environment + +When this environment is built, the Apache 2 service is automatically started, with the root folder of the Winter project being used. A preview of the website will be opened immediately - if you do not see this, you can open the **Ports** tab in VSCode to view the URL generated for viewing the project. + +XDebug is enabled by default, and allows you to quickly use step debugging. It will be available in the **Debug** tab of VSCode or similar screen in other IDEs. + +By default, when using the `bootstrap-winter` feature, changes to certain folders and locations will be ignored by Git to keep the change list clean. This includes the `plugins` and `themes` folders, and `composer.json` in the root folder. If you wish to use this environment for your own projects, it is recommended that you do not use this feature. Please see the **Using in your own projects** section below for using this environment outside of Winter development. + +## Environment platform + +The following software is installed in this environment. + +- Apache 2.4 +- PHP 8.3 with the following extensions: + - `intl` + - `gd` + - `xdebug` +- Composer +- NodeJS 22 (including `npm`) +- Git + +## Using in your own projects + +You may use this development environment for your own projects, making it a great starting point to hit the ground running with Winter. It is recommended that you *disable* the `bootstrap-winter` feature when using this environment for your own projects. + +You may disable this feature by modifying the `.devcontainer/devcontainer.json` file before running the container and commenting out the feature: + +```json + "ghcr.io/devcontainers/features/git:1": {}, + "./local-features/apache-config": "latest", + // Comment the following feature if you wish to bootstrap and configure Winter manually (ie. you wish to use this for your own project) + //"./local-features/bootstrap-winter": "latest" + }, + "overrideFeatureInstallOrder": [ +``` + +If this feature is disabled, you must bootstrap your project manually. This includes: + +- Downloading the Composer dependencies. +- Generating the configuration for the project, either as an `.env` file or in the `config` folder. +- Finally, Running the database migrations. + +You may view the `.devcontainer/local-features/bootstrap-winter/bootstrap.sh` file to see how we bootstrap Winter, and run these commands manually. You will only need to do this once per project container. + +If you wish to mount your own volumes, use your own databases or any other complex usages, please review the [Docker documentation](https://docs.docker.com/) to set this up on the container. diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index 926326f8a..e1b5c7b73 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -19,7 +19,6 @@ "version": "22" }, "ghcr.io/devcontainers/features/git:1": {}, - "ghcr.io/devcontainers/features/github-cli:1": {}, "./local-features/apache-config": "latest", // Comment the following feature if you wish to bootstrap and configure Winter manually (ie. you wish to use this for your own project) "./local-features/bootstrap-winter": "latest" @@ -33,9 +32,6 @@ }, "postStartCommand": "sudo rm -rf /var/www/html && sudo ln -s ${containerWorkspaceFolder} /var/www/html && service apache2 start", "portsAttributes": { - "80": { - "onAutoForward": "ignore" - }, "8080": { "label": "Preview Winter installation", "onAutoForward": "openPreview" @@ -48,7 +44,8 @@ "customizations": { "vscode": { "settings": { - "php.validate.executablePath": "/usr/local/bin/php" + "php.validate.executablePath": "/usr/local/bin/php", + "phpcs.executablePath": "${containerWorkspaceFolder}/vendor/bin/phpcs" }, "extensions": [ "xdebug.php-debug", @@ -57,6 +54,11 @@ "swordev.phpstan", "wintercms.winter-cms" ] + }, + "codespaces": { + "openFiles": [ + ".devcontainer/README.md" + ] } }, "remoteUser": "vscode"