diff --git a/.github/workflows/previews.yaml b/.github/workflows/previews.yaml index adf14325db8..e5aa5dfa636 100644 --- a/.github/workflows/previews.yaml +++ b/.github/workflows/previews.yaml @@ -14,36 +14,53 @@ env: JETPACK_SECRET_KEY: ${{ secrets.JETPACK_SECRET_KEY }} jobs: - deploy-docs-preview: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - - uses: dorny/paths-filter@v2 - id: filter - with: - filters: | - docs: - - 'docs/**' - - uses: bahmutov/npm-install@v1 - if: steps.filter.outputs.docs == 'true' - with: - working-directory: docs/app - - name: Mount docs node_modules - if: steps.filter.outputs.docs == 'true' - uses: actions/cache@v3 - with: - path: docs/app/node_modules - key: docs-node-modules - - name: Docs build - if: steps.filter.outputs.docs == 'true' - run: | - yarn install - yarn run build + markdown-lint: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - uses: dorny/paths-filter@v2 + id: filter + with: + filters: | + docs: + - 'docs/**' + - name: markdownlint-cli + uses: nosborn/github-action-markdown-cli@v3.2.0 + with: + files: docs/app/docs + config_file: docs/.markdownlint.yaml + + deploy-to-preview: + runs-on: ubuntu-latest + needs: markdown-lint + steps: + - uses: actions/checkout@v3 + - uses: dorny/paths-filter@v2 + id: filter + with: + filters: | + docs: + - 'docs/**' + - uses: bahmutov/npm-install@v1 + if: steps.filter.outputs.docs == 'true' + with: working-directory: docs/app - - name: Deploy docs preview - if: steps.filter.outputs.docs == 'true' - run: | - curl https://get.jetpack.io -fsSL | bash -s -- -y - jetpack up docs \ - --ttl 300 --debug \ - -n jetpack-io-preview-$(echo "${GITHUB_REF_NAME}" | sed "s/[^0-9a-zA-Z]/-/g") + - name: Mount docs node_modules + if: steps.filter.outputs.docs == 'true' + uses: actions/cache@v3 + with: + path: docs/app/node_modules + key: docs-node-modules + - name: Docs build + if: steps.filter.outputs.docs == 'true' + run: | + yarn install + yarn run build + working-directory: docs/app + - name: Deploy docs preview + if: steps.filter.outputs.docs == 'true' + run: | + curl https://get.jetpack.io -fsSL | bash -s -- -y + jetpack up docs \ + --ttl 300 --debug \ + -n jetpack-io-preview-$(echo "${GITHUB_REF_NAME}" | sed "s/[^0-9a-zA-Z]/-/g") diff --git a/docs/.markdownlint.yaml b/docs/.markdownlint.yaml new file mode 100644 index 00000000000..fb940393d6b --- /dev/null +++ b/docs/.markdownlint.yaml @@ -0,0 +1,10 @@ +# Autoformatter friendly markdownlint config (all formatting rules disabled) +default: true +blank_lines: false +bullet: false +html: false +indentation: false +line_length: false +spaces: false +url: false +whitespace: false diff --git a/docs/app/README.md b/docs/README.md similarity index 57% rename from docs/app/README.md rename to docs/README.md index aaba2fa1e16..8aa4c0a530c 100644 --- a/docs/app/README.md +++ b/docs/README.md @@ -5,7 +5,9 @@ This website is built using [Docusaurus 2](https://docusaurus.io/), a modern sta ### Installation ``` -$ yarn +$ cd docs/app # from the devbox root directory +$ devbox shell # optional, develop inside a devbox +$ yarn install # run in devbox shell ``` ### Local Development @@ -26,16 +28,6 @@ This command generates static content into the `build` directory and can be serv ### Deployment -Using SSH: - -``` -$ USE_SSH=true yarn deploy -``` - -Not using SSH: - -``` -$ GIT_USER= yarn deploy -``` - -If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch. +When a pull request is opened, it will automatically deploy via CICD to a preview. +When a pull request is merged, it will automatically deploy to production. +Check https://www.jetpack.io/devbox/ after merge to see the latest changes. diff --git a/docs/app/devbox.json b/docs/app/devbox.json new file mode 100644 index 00000000000..3352a1b2467 --- /dev/null +++ b/docs/app/devbox.json @@ -0,0 +1,6 @@ +{ + "packages": [], + "shell": { + "init_hook": null + } +} \ No newline at end of file diff --git a/docs/app/docs/configuration.md b/docs/app/docs/configuration.md index 41a4bb7ef0e..b29a42c3ffb 100644 --- a/docs/app/docs/configuration.md +++ b/docs/app/docs/configuration.md @@ -14,8 +14,8 @@ Your devbox configuration is stored in a `devbox.json` file, located in your pro "install_stage": { "command": "..." }, - "build_stage":{ - "command":"..." + "build_stage": { + "command": "..." }, "start_stage": { "command": "..." @@ -45,7 +45,7 @@ This is an example `devbox.json` that customizes the prompt and prints a welcome When run, you'll see: -``` +```text > devbox shell Installing nix packages. This may take a while... Starting a devbox shell... @@ -57,9 +57,9 @@ Welcome! See CONTRIBUTING.md for tips on contributing to devbox. Stages are used to configure and run commands at different points of container creation. For languages that support autodetction, Devbox will automatically detect and configure the correct stage commands for your project based on your source code. You can override any of these stages by configuring them in your devbox.json -* The **install stage** will run after your base container has been initialized and your Nix packages are installed. This stage should be used to download and build your application's dependencies -* The **build stage** runs after the install stage, and should be used to build or bundle your application. -* The **start stage** will run when your container is started. This stage should include any commands needed to start and run your application. +- The **install stage** will run after your base container has been initialized and your Nix packages are installed. This stage should be used to download and build your application's dependencies +- The **build stage** runs after the install stage, and should be used to build or bundle your application. +- The **start stage** will run when your container is started. This stage should include any commands needed to start and run your application. Each stage takes a single command that will be run when the stage is reached in your container build. diff --git a/docs/app/docs/installing_devbox.md b/docs/app/docs/installing_devbox.md index aea9f065a84..9b25af96a3e 100644 --- a/docs/app/docs/installing_devbox.md +++ b/docs/app/docs/installing_devbox.md @@ -11,10 +11,10 @@ In addition to installing Devbox itself, you will need to install nix and docker 2. Install [Docker Engine](https://docs.docker.com/engine/install/) or [Docker Desktop](https://www.docker.com/get-started/). Note that docker is only needed if you want to create containers – the shell functionality works without it. -## Install Devbox: +## Install Devbox Use the following install script to get the latest version of Devbox: -``` +```bash curl -fsSL https://get.jetpack.io/devbox | bash -``` \ No newline at end of file +``` diff --git a/docs/app/docs/language_support/nginx.md b/docs/app/docs/language_support/nginx.md index 8ac99126953..55752e901fd 100644 --- a/docs/app/docs/language_support/nginx.md +++ b/docs/app/docs/language_support/nginx.md @@ -21,7 +21,7 @@ Devbox will use the nginx provided by the Nix Package manager. It is currently n ### Included Nix Packages -- `nginx` +- `nginx` ### Default Stages @@ -29,14 +29,14 @@ These stages can be customized by adding them to your `devbox.json`. See the [Co ### Install Stage -*No install stage for nginx planner* +Skipped: _No install stage for nginx planner_ ### Build Stage -*No build stage for nginx planner* +Skipped: _No build stage for nginx planner_ ### Start Stage ```bash nginx -c -g 'daemon off;' -``` \ No newline at end of file +``` diff --git a/docs/app/docs/language_support/nodejs.md b/docs/app/docs/language_support/nodejs.md index 39f7482aeaa..663b7d82fad 100644 --- a/docs/app/docs/language_support/nodejs.md +++ b/docs/app/docs/language_support/nodejs.md @@ -9,54 +9,89 @@ Devbox will automatically create a NodeJs Build plan whenever a `package.json` f ### Supported Versions Devbox will attempt to detect the Node version set in your `package.json` file. The following major versions are supported (Devbox will always use the latest minor version for each major version): -* 10 -* 12 -* 16 -* 18 + +- 10 +- 12 +- 16 +- 18 If no version is set, Devbox will use 16 as the default version ### Included Nix Packages -* Depending on the detected Node Version: - * `nodejs` - * `nodejs10_x` - * `nodejs12_x` - * `nodejs16_x` - * `nodejs18_x` -* If a `package-lock.json` is detected, or if no lockfile is detected: - * `npm` -* If a `yarn.lock` file is detected: - * `yarn` - +- Depending on the detected Node Version: + - `nodejs` + - `nodejs10_x` + - `nodejs12_x` + - `nodejs16_x` + - `nodejs18_x` +- If a `package-lock.json` is detected, or if no lockfile is detected: + - `npm` +- If a `yarn.lock` file is detected: + - `yarn` ### Default Stages These stages can be customized by adding them to your `devbox.json`. See the [Configuration Guide](../configuration.md) for more details -#### Install Stage + +### Install Stage If a `package-lock.json` is detected: + ```bash npm install ``` -If a `yarn.lock` is detected: +If a `yarn.lock` is detected: + ```bash yarn install ``` -Otherwise: +Otherwise: ```bash npm install ``` -#### Build Stage +### Build Stage + +This stage will copy over the rest of your project files. + +If a `package-lock.json` is detected and a `build` script is found in `package.json`: + +```bash +npm run build && npm prune --production +``` + +If a `yarn.lock` is detected and a `build` script is found in `package.json`: -This stage will copy over the rest of your project files, but will not run a command. +```bash +yarn build && yarn install --production --ignore-scripts --prefer-offline +``` -#### Start Stage +Otherwise, we simply remove the dev packages: + +```bash +npm prune --production +``` + +### Start Stage + +If a `package-lock.json` is detected and a `start` script is found in `package.json`: + +```bash +npm start +``` + +If a `yarn.lock` is detected and a `start` script is found in `package.json`: + +```bash +yarn start +``` + +Otherwise: ```bash node index.js -``` \ No newline at end of file +``` diff --git a/docs/app/docs/language_support/php.md b/docs/app/docs/language_support/php.md index a6e624dd952..35ebd8e7b02 100644 --- a/docs/app/docs/language_support/php.md +++ b/docs/app/docs/language_support/php.md @@ -4,27 +4,27 @@ title: PHP ### Detection -Devbox will automatically create a PHP Build plan whenever a `composer.json` or `composer.lock` file is detected in the project's root directory. +Devbox will automatically create a PHP Build plan whenever a `composer.json` or `composer.lock` file is detected in the project's root directory. -Building a container with Devbox also requires a `public/index.php` file in your project directory. Running `devbox build` will return an error if one is not found. +Building a container with Devbox also requires a `public/index.php` file in your project directory. Running `devbox build` will return an error if one is not found. ### Supported Versions Devbox will attempt to detect the PHP version set in your `composer.json` file. The following major versions are supported (Devbox will always use the latest minor version for each major version): -* 7.4 -* 8.0 -* 8.1 + +- 7.4 +- 8.0 +- 8.1 If no version is set, Devbox will use 8.1 as the default version ### Included Nix Packages -* Depending on the detected PHP Version: - * `php81` - * `php80` - * `php74` -* `phpPackages.composer` - +- Depending on the detected PHP Version: + - `php81` + - `php80` + - `php74` +- `phpPackages.composer` ### Default Stages @@ -36,10 +36,9 @@ These stages can be customized by adding them to your `devbox.json`. See the [Co composer install --no-dev --no-ansi ``` - #### Build Stage -*This stage is skipped for PHP projects* +Skipped: _This stage is skipped for PHP projects_ #### Start Stage diff --git a/docs/app/docs/quickstart.md b/docs/app/docs/quickstart.md index cde3ec00ae8..a73f4a4a6d9 100644 --- a/docs/app/docs/quickstart.md +++ b/docs/app/docs/quickstart.md @@ -3,7 +3,6 @@ title: Quickstart sidebar_position: 3 --- - ## Create an isolated development shell In this quickstart we’ll create a development shell with specific tools installed. These tools will only be available when using this Devbox shell, ensuring we don’t pollute your machine. @@ -12,54 +11,53 @@ In this quickstart we’ll create a development shell with specific tools instal 2. Initialize Devbox: - ```bash - devbox init - ``` + ```bash + devbox init + ``` - This creates a `devbox.json` file in the current directory. You should commit it to source control. + This creates a `devbox.json` file in the current directory. You should commit it to source control. 3. Add command-line tools from [Nix Packages](https://search.nixos.org/packages). For example, to add Python 3.10: - ```bash - devbox add python310 - ``` + ```bash + devbox add python310 + ``` + 4. Your `devbox.json` file keeps track of the packages you've added, it should now look like this: - ```json - { - "packages": [ - "python310" - ] - } - ``` + ```json + { + "packages": ["python310"] + } + ``` 5. Start a new shell that has these tools installed: - ```bash - devbox shell - ``` + ```bash + devbox shell + ``` - You can tell you’re in a Devbox shell (and not your regular terminal) because the shell prompt and directory changed. + You can tell you’re in a Devbox shell (and not your regular terminal) because the shell prompt and directory changed. 6. Use your favorite tools. - In this example we installed Python 3.10, so let’s use it. + In this example we installed Python 3.10, so let’s use it. - ```bash - python --version - ``` + ```bash + python --version + ``` 7. Your regular tools are also available including environment variables and config settings. - ```bash - git config --get user.name - ``` + ```bash + git config --get user.name + ``` 8. To exit the Devbox shell and return to your regular shell: - ```bash - exit - ``` + ```bash + exit + ``` ## Package your application as a Docker Image @@ -69,20 +67,26 @@ Devbox makes it easy to package your application into an OCI-compliant container 2. Build the image: - ```bash - devbox build - ``` + ```bash + devbox build + ``` - The resulting image is named `devbox`. + The resulting image is named `devbox`. 3. Tag the image with a more descriptive name: - ```bash - docker tag devbox my-image:v0.1 - ``` -### Auto-detected languages: + ```bash + docker tag devbox my-image:v0.1 + ``` + +### Auto-detected languages + Devbox currently detects the following languages: -- Go +- Go +- Python (Poetry) +- NodeJS +- PHP +- static nginx (Experimental) -Want more languages? [Ask for a new Language](https://github.com/jetpack-io/devbox/issues) or contribute one via a Pull Request. \ No newline at end of file +Want more languages? [Ask for a new Language](https://github.com/jetpack-io/devbox/issues) or contribute one via a Pull Request.