ghost/.devcontainer/README.md

# Dev Container Setup

## devcontainer.json
This file contains the configuration for the dev container. It is used to define the setup of the container, including things like port bindings, environment variables, and other dev container specific features.

There are three main components that the devcontainer.json file relies on:
- The docker compose file (`.devcontainer/compose.yml`), which defines all the services that should be started when the dev container is launched, like MySQL and Redis.
- The Dockerfile (`.docker/Dockerfile`), which is used to build the dev container image.
- The `onCreateCommand` script (`.devcontainer/onCreateCommand.js`), which is used to setup the dev container after it is created.

The Dev Container setup is intended to be as simple as possible with a focus on a really simple setup experience. It is designed to use VSCode's "Clone Repository in Container" feature, which will automatically handle the setup of the dev container, and create a volume for the Ghost codebase that is managed by Docker. It is a great tool for quickly spinning up an isolated development environment, but it lacks some of the flexibility and direct control that a full docker compose setup can provide. Therefore, if you plan to do more "heavy lifting" on Ghost, we recommend using the docker compose setup instead.

## Dockerfile
The Dockerfile used to build the Dev Container itself is located at `.docker/Dockerfile`. This Dockerfile uses a multi-stage build to allow for multiple types of builds without duplicating code and ensuring maximum consistency. The following targets are available:
- `base`: The bare minimum base image used to build and run Ghost. Includes the operating system, node, and some build dependencies, but does not include any Ghost code or dependencies.
- `base-devcontainer`: everything from `base`, plus additional development dependencies like the stripe-cli and playwright. No code or node dependencies.
- `full-devcontainer`: everything from `base-devcontainer`, plus Ghost's code and all node dependencies
- `development`: an alternative to `full-devcontainer` intended for manual development e.g. with docker compose. Add Ghost's code and installs dependencies with some optimizations for the yarn cache

## Docker Compose
The docker compose setup for the dev container is located at `.devcontainer/compose.yml`. This compose file includes the MySQL database service and the Redis service, in addition to the Ghost dev container service. When running the Dev Container (i.e. via the "Clone Repository in Container" feature in VSCode), this compose file will be used to start the necessary services before starting the Ghost Dev Container itself.

## On Create Command
The Dev Container spec allows developers to specify a command to run after the container is created. This is done by specifying an `onCreateCommand` in the devcontainer.json file. For Ghost's Dev Container, this command simply runs a JS script defined in `.devcontainer/onCreateCommand.js`. This script handles installing node dependencies, setting up the local configuration at `ghost/core/config.local.json`, and some other simple setup tasks to get the dev container ready for use.
Added Dev Container setup (#21279) no issue - Dev Containers let you work on Ghost in a consistent, isolated environment with all the necessary development dependencies pre-installed. VSCode (or Cursor) can effectively run _inside_ the container, providing a local quality development environment while working in a well-defined, isolated environment. - For now the default setup only works with "Clone repository in Container Volume" or "Clone PR in Container Volume" — this allows for a super quick and simple setup. We can also introduce another configuration to allow opening an existing local checkout in a Dev Container, but that's not quite ready yet. - This PR also added the `yarn clean:hard` command which: deletes all node_modules, cleans the yarn cache, and cleans the NX cache. This will be necessary for opening a local checkout in a Dev Container. - To learn more about Dev Containers, read this guide from VSCode: https://code.visualstudio.com/docs/devcontainers/containers#_personalizing-with-dotfile-repositories --------- Co-authored-by: Joe Grigg <joe@ghost.org> Co-authored-by: Steve Larson <9larsons@gmail.com> 2024-10-24 13:15:08 -05:00			`# Dev Container Setup`

			`## devcontainer.json`
			`This file contains the configuration for the dev container. It is used to define the setup of the container, including things like port bindings, environment variables, and other dev container specific features.`

Simplified Dev Container setup to use a single compose file (#21649) no issue - The current devcontainer setup was built with the intention of using it as the _primary_ way of running Ghost in Docker locally. As such, it was designed to be extensible — there was a `base.compose.yml` file with the default configuration, and multiple other `compose.yml` files that could be added to extend the base setup to cover different use-cases. - We've run into some problems with using the devcontainer for regular day to day usage, so we're moving toward using a more conventional `compose` based setup for more advanced configurations. - We're going to keep the devcontainer around as it's still nice for a quick and easy setup, but it no longer needs to support multiple configurations — as such, we can simplify the setup to a single `compose.yml` file to make it easier to reason about and troubleshoot if anything goes wrong. - This commit removes the `.devcontainer/.docker` directory, and many of the files that were in it. The main `compose.yml` file and the Dockerfile were moved to the root of `.devcontainer` which should make the setup a bit easier to follow and modify as needed. 2024-11-18 17:15:11 -05:00			`There are three main components that the devcontainer.json file relies on:`
			- The docker compose file (`.devcontainer/compose.yml`), which defines all the services that should be started when the dev container is launched, like MySQL and Redis.
Reorganized docker related files (#21650) ref https://linear.app/ghost/issue/ENG-1782/move-docker-related-files-to-a-better-location-that-githubscripts - The docker files are currently located in `.github/scripts`. This location doesn't make a lot of sense — you wouldn't think to look there unless you already knew they were there. This also requires you to specify the path to the `compose.yml` file whenever running a `docker compose ...` command. - This commit moves the `compose.yml` file to the root of the repo, so you can simply run `docker compose up` and it will automatically find the file in the root, without having to specify `-f .github/scripts/docker-compose.yml`. This is a major win for convenience over the current setup. - It also moves all the related files, including the `Dockerfile` used by the Dev Container setup and configuration files for supporting services into a new `.docker` directory, which is a more logical location, and should be easier to find. - Also updated the current convenience commands in the `package.json` scripts block (`yarn docker:reset` and `yarn docker:down` 2024-11-19 16:15:06 -05:00			- The Dockerfile (`.docker/Dockerfile`), which is used to build the dev container image.
Simplified Dev Container setup to use a single compose file (#21649) no issue - The current devcontainer setup was built with the intention of using it as the _primary_ way of running Ghost in Docker locally. As such, it was designed to be extensible — there was a `base.compose.yml` file with the default configuration, and multiple other `compose.yml` files that could be added to extend the base setup to cover different use-cases. - We've run into some problems with using the devcontainer for regular day to day usage, so we're moving toward using a more conventional `compose` based setup for more advanced configurations. - We're going to keep the devcontainer around as it's still nice for a quick and easy setup, but it no longer needs to support multiple configurations — as such, we can simplify the setup to a single `compose.yml` file to make it easier to reason about and troubleshoot if anything goes wrong. - This commit removes the `.devcontainer/.docker` directory, and many of the files that were in it. The main `compose.yml` file and the Dockerfile were moved to the root of `.devcontainer` which should make the setup a bit easier to follow and modify as needed. 2024-11-18 17:15:11 -05:00			- The `onCreateCommand` script (`.devcontainer/onCreateCommand.js`), which is used to setup the dev container after it is created.

			The Dev Container setup is intended to be as simple as possible with a focus on a really simple setup experience. It is designed to use VSCode's "Clone Repository in Container" feature, which will automatically handle the setup of the dev container, and create a volume for the Ghost codebase that is managed by Docker. It is a great tool for quickly spinning up an isolated development environment, but it lacks some of the flexibility and direct control that a full docker compose setup can provide. Therefore, if you plan to do more "heavy lifting" on Ghost, we recommend using the docker compose setup instead.
Added Dev Container setup (#21279) no issue - Dev Containers let you work on Ghost in a consistent, isolated environment with all the necessary development dependencies pre-installed. VSCode (or Cursor) can effectively run _inside_ the container, providing a local quality development environment while working in a well-defined, isolated environment. - For now the default setup only works with "Clone repository in Container Volume" or "Clone PR in Container Volume" — this allows for a super quick and simple setup. We can also introduce another configuration to allow opening an existing local checkout in a Dev Container, but that's not quite ready yet. - This PR also added the `yarn clean:hard` command which: deletes all node_modules, cleans the yarn cache, and cleans the NX cache. This will be necessary for opening a local checkout in a Dev Container. - To learn more about Dev Containers, read this guide from VSCode: https://code.visualstudio.com/docs/devcontainers/containers#_personalizing-with-dotfile-repositories --------- Co-authored-by: Joe Grigg <joe@ghost.org> Co-authored-by: Steve Larson <9larsons@gmail.com> 2024-10-24 13:15:08 -05:00
			`## Dockerfile`
Reorganized docker related files (#21650) ref https://linear.app/ghost/issue/ENG-1782/move-docker-related-files-to-a-better-location-that-githubscripts - The docker files are currently located in `.github/scripts`. This location doesn't make a lot of sense — you wouldn't think to look there unless you already knew they were there. This also requires you to specify the path to the `compose.yml` file whenever running a `docker compose ...` command. - This commit moves the `compose.yml` file to the root of the repo, so you can simply run `docker compose up` and it will automatically find the file in the root, without having to specify `-f .github/scripts/docker-compose.yml`. This is a major win for convenience over the current setup. - It also moves all the related files, including the `Dockerfile` used by the Dev Container setup and configuration files for supporting services into a new `.docker` directory, which is a more logical location, and should be easier to find. - Also updated the current convenience commands in the `package.json` scripts block (`yarn docker:reset` and `yarn docker:down` 2024-11-19 16:15:06 -05:00			The Dockerfile used to build the Dev Container itself is located at `.docker/Dockerfile`. This Dockerfile uses a multi-stage build to allow for multiple types of builds without duplicating code and ensuring maximum consistency. The following targets are available:
Added Dev Container setup (#21279) no issue - Dev Containers let you work on Ghost in a consistent, isolated environment with all the necessary development dependencies pre-installed. VSCode (or Cursor) can effectively run _inside_ the container, providing a local quality development environment while working in a well-defined, isolated environment. - For now the default setup only works with "Clone repository in Container Volume" or "Clone PR in Container Volume" — this allows for a super quick and simple setup. We can also introduce another configuration to allow opening an existing local checkout in a Dev Container, but that's not quite ready yet. - This PR also added the `yarn clean:hard` command which: deletes all node_modules, cleans the yarn cache, and cleans the NX cache. This will be necessary for opening a local checkout in a Dev Container. - To learn more about Dev Containers, read this guide from VSCode: https://code.visualstudio.com/docs/devcontainers/containers#_personalizing-with-dotfile-repositories --------- Co-authored-by: Joe Grigg <joe@ghost.org> Co-authored-by: Steve Larson <9larsons@gmail.com> 2024-10-24 13:15:08 -05:00			- `base`: The bare minimum base image used to build and run Ghost. Includes the operating system, node, and some build dependencies, but does not include any Ghost code or dependencies.
			- `base-devcontainer`: everything from `base`, plus additional development dependencies like the stripe-cli and playwright. No code or node dependencies.
			- `full-devcontainer`: everything from `base-devcontainer`, plus Ghost's code and all node dependencies
			- `development`: an alternative to `full-devcontainer` intended for manual development e.g. with docker compose. Add Ghost's code and installs dependencies with some optimizations for the yarn cache

			`## Docker Compose`
Simplified Dev Container setup to use a single compose file (#21649) no issue - The current devcontainer setup was built with the intention of using it as the _primary_ way of running Ghost in Docker locally. As such, it was designed to be extensible — there was a `base.compose.yml` file with the default configuration, and multiple other `compose.yml` files that could be added to extend the base setup to cover different use-cases. - We've run into some problems with using the devcontainer for regular day to day usage, so we're moving toward using a more conventional `compose` based setup for more advanced configurations. - We're going to keep the devcontainer around as it's still nice for a quick and easy setup, but it no longer needs to support multiple configurations — as such, we can simplify the setup to a single `compose.yml` file to make it easier to reason about and troubleshoot if anything goes wrong. - This commit removes the `.devcontainer/.docker` directory, and many of the files that were in it. The main `compose.yml` file and the Dockerfile were moved to the root of `.devcontainer` which should make the setup a bit easier to follow and modify as needed. 2024-11-18 17:15:11 -05:00			The docker compose setup for the dev container is located at `.devcontainer/compose.yml`. This compose file includes the MySQL database service and the Redis service, in addition to the Ghost dev container service. When running the Dev Container (i.e. via the "Clone Repository in Container" feature in VSCode), this compose file will be used to start the necessary services before starting the Ghost Dev Container itself.
Added Dev Container setup (#21279) no issue - Dev Containers let you work on Ghost in a consistent, isolated environment with all the necessary development dependencies pre-installed. VSCode (or Cursor) can effectively run _inside_ the container, providing a local quality development environment while working in a well-defined, isolated environment. - For now the default setup only works with "Clone repository in Container Volume" or "Clone PR in Container Volume" — this allows for a super quick and simple setup. We can also introduce another configuration to allow opening an existing local checkout in a Dev Container, but that's not quite ready yet. - This PR also added the `yarn clean:hard` command which: deletes all node_modules, cleans the yarn cache, and cleans the NX cache. This will be necessary for opening a local checkout in a Dev Container. - To learn more about Dev Containers, read this guide from VSCode: https://code.visualstudio.com/docs/devcontainers/containers#_personalizing-with-dotfile-repositories --------- Co-authored-by: Joe Grigg <joe@ghost.org> Co-authored-by: Steve Larson <9larsons@gmail.com> 2024-10-24 13:15:08 -05:00
Simplified Dev Container setup to use a single compose file (#21649) no issue - The current devcontainer setup was built with the intention of using it as the _primary_ way of running Ghost in Docker locally. As such, it was designed to be extensible — there was a `base.compose.yml` file with the default configuration, and multiple other `compose.yml` files that could be added to extend the base setup to cover different use-cases. - We've run into some problems with using the devcontainer for regular day to day usage, so we're moving toward using a more conventional `compose` based setup for more advanced configurations. - We're going to keep the devcontainer around as it's still nice for a quick and easy setup, but it no longer needs to support multiple configurations — as such, we can simplify the setup to a single `compose.yml` file to make it easier to reason about and troubleshoot if anything goes wrong. - This commit removes the `.devcontainer/.docker` directory, and many of the files that were in it. The main `compose.yml` file and the Dockerfile were moved to the root of `.devcontainer` which should make the setup a bit easier to follow and modify as needed. 2024-11-18 17:15:11 -05:00			`## On Create Command`
			The Dev Container spec allows developers to specify a command to run after the container is created. This is done by specifying an `onCreateCommand` in the devcontainer.json file. For Ghost's Dev Container, this command simply runs a JS script defined in `.devcontainer/onCreateCommand.js`. This script handles installing node dependencies, setting up the local configuration at `ghost/core/config.local.json`, and some other simple setup tasks to get the dev container ready for use.