diff --git a/.algolia/docsearch.config.json b/.algolia/docsearch.config.json index 6b018b2477..6eb543d468 100644 --- a/.algolia/docsearch.config.json +++ b/.algolia/docsearch.config.json @@ -1,34 +1,38 @@ { "index_name": "documentation", "start_urls": [ - "https://docs.strapi.io" + { + "url": "https://docs.strapi.io" + } ], "selectors": { - "lvl0": { - "selector": "(//*[contains(@class, 'sidebar-heading open')])[1]", - "type": "xpath", - "global": true - }, - "lvl1": { - "selector": "//h1/text()", - "type": "xpath", - "global": true - }, - "lvl2": { - "selector": "/html/head/meta[@name='description']/@content", - "type": "xpath", - "global": true - }, - "lvl4": { - "selector": "//h2/text()", - "type": "xpath", - "global": true - }, - "text": ".content__default p", - "lang": { - "selector": "/html/@lang", - "type": "xpath", - "global": true + "default": { + "lvl0": { + "selector": "(//*[contains(@class, 'sidebar-heading open')])[1]", + "type": "xpath", + "global": true + }, + "lvl1": { + "selector": "//h1/text()", + "type": "xpath", + "global": true + }, + "lvl2": { + "selector": "/html/head/meta[@name='description']/@content", + "type": "xpath", + "global": true + }, + "lvl3": { + "selector": "//h2/text()", + "type": "xpath", + "global": true + }, + "text": ".content__default p, .content__default ul>li a, .content__default ul>li code", + "lang": { + "selector": "/html/@lang", + "type": "xpath", + "global": true + } } }, "strip_chars": " .,;:#", @@ -40,4 +44,4 @@ "lang" ] } -} \ No newline at end of file +} diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index aa36cf03e1..7ec0d7f595 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,47 +6,44 @@ All efforts to contribute are highly appreciated, we recommend you talk to a mai ## Open Development & Community Driven -Strapi is an open-source project. See the [LICENSE](https://github.com/strapi/documentation/blob/main/LICENSE) file for licensing information. All the work done is available on GitHub. +Strapi is an open-source project. See the [LICENSE](https://github.com/strapi/documentation/blob/main/LICENSE) file for licensing information. All of the work is available on GitHub. The core team and the contributors send pull requests which go through the same validation process. -## Documentation Requests +## Code of Conduct -Requests for new documentation are highly encouraged, this is not limited to new additions but also changes or more information requested on existing documentation. Please use our [request documentation](https://github.com/strapi/documentation/issues/new?template=DOC_REQUEST.md&title%5B%5D=REQUEST) issue template. +This project and everyone participating in it are governed by the [Strapi Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold the code. -## Code of Conduct +## Documentation Requests -This project and everyone participating in it are governed by the [Strapi Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please read the [full text](CODE_OF_CONDUCT.md) so that you can read which actions may or may not be tolerated. +Requests for new documentation are highly encouraged, this is not limited to new additions but also changes or more information requested on existing documentation. Please use our [request documentation](https://github.com/strapi/documentation/issues/new?template=DOC_REQUEST.md&title%5B%5D=REQUEST) issue template. If you are requesting documentation, please feel free to open a pull request. ## Bugs -We are using [GitHub Issues](https://github.com/strapi/documentation/issues) to manage our public bugs. Before submitting an issue you need to make sure: +Bug reports help to improve the documentation. Please use our [Documentation Bug Report](https://github.com/strapi/documentation/issues/new?template=BUG_REPORT.yml) template to report documentation bugs. Before submitting an issue: -- Checked for any existing pull requests that may address the same issue -- Checked for any open issues related to your issue, if so, please provide context on that issue -- Follow the issue template and try to fill out as much information as you can - - Issues not following the templates **will be closed** - - You may update the closed issue with the required information and it will be reopened -- The issue is with the Strapi **documentation only**, code issues should be directed at the main [strapi/strapi](https://github.com/strapi/strapi) repo issues -- If you are requesting documentation, please do feel free to make a pull request - - Documentation requests will be handled when we have free room within our roadmap - - Open requests **are not handled** in a "first come, first serve" basis, they are handled on a "best-effort" depending on the time required to produce -- Do not ask technical questions about how to do something - - Questions should be directed at the following resources - - Open a Q&A thread on our [Official Forum](https://forum.strapi.io) - - Talk with other community members on our [Community Discord](https://discord.strapi.io) +- Check for existing pull requests that may address the same issue. +- Check for related open issues, if so, please provide context on the existing issue. +- Follow the issue template and fill out as much information as you can. +- Verify the issue is only with the Strapi documentation, code issues should be directed at the main [strapi/strapi](https://github.com/strapi/strapi) repository. + +Technical questions should be asked using the following resources: -Please note that rude or impolite comments on issues that violate our [Code of Conduct](./CODE_OF_CONDUCT.md) will be deleted and issues that violate the COC will be closed. +- Open a Q&A thread on our [Official Forum](https://forum.strapi.io) +- Engage with other community members on our [Community Discord](https://discord.strapi.io) --- -## Submitting a Pull Request +## Pull Requests -The core team will review your pull request and will either merge it, request changes to it, or close it. +The core team reviews community pull requests and either merges, requests changes, or comments and closes the pull request. You can open a documentation pull request by: -### Setup and pull request creation +- clicking the `Improve this page` link at the bottom of any documentation page to directly edit in GitHub, +- forking the `documentation` repository and working locally. -Follow the procedure below to contribute to the Strapi documentation. +### Setup and write locally + +The following procedure allows you to work locally on the Strapi documentation. 1. Fork the `documentation` repository. 2. Clone your forked `documentation` repository. @@ -65,7 +62,7 @@ Follow the procedure below to contribute to the Strapi documentation. cd documentation/docs/user-docs ``` -4. Choose the branch from which to work: either `main` for a contribution on the latest, current version or Strapi ; or `v[x]` for a contribution on a previous version of Strapi. +4. Choose the branch from which to work: either `main` for a contribution on the current version of Strapi or `v[x]` for a contribution on a previous version of Strapi. ```bash #current version of Strapi (i.e. v4) @@ -86,7 +83,7 @@ Follow the procedure below to contribute to the Strapi documentation. git pull ``` -6. Create your own branch, based on either `main` or `v[x]` , on which you will work on your documentation contribution. Make sure the name of your branch indicates both the type of documentation and the topic. +6. Create your branch, based on either `main` or `v[x]`, to work on your documentation contribution. Make sure your branch name indicates both the type of documentation and the topic. ```bash # developer documentation @@ -118,43 +115,31 @@ Follow the procedure below to contribute to the Strapi documentation. The project is now up and running at http://localhost:8080 and you should be able to access it in your browser. - You are now ready to contribute to the Strapi documentation! 🚀 -🤗 Make sure to follow the [12 Rules of Technical Writing](https://handbook.strapi.io/user-success-manual/12-rules-of-technical-writing) and the [Strapi Documentation Style Guide](https://handbook.strapi.io/user-success-manual/strapi-documentation-style-guide) when writing your documentation contribution. These documents are meant to help you write a contribution that fits the whole Strapi documentation and make the reviewing process easier and quicker. - -When you are finished writing, create a pull request from your forked repository to the original `documentation` repository (see [the GitHub docs](https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork) for more information). +### Write technical documentation -✋ To be able to submit your contribution, you must sign the CLA (Contributor License Agreement), directly via GitHub (see [our dedicated blog post](https://strapi.io/blog/switching-from-dco-to-cla) for more information). +For lengthier contributions, we provide general guidelines that can help you write clear and concise documentation: -### Pull request review and management +- The [12 Rules of Technical Writing](https://handbook.strapi.io/user-success-manual/12-rules-of-technical-writing) gives an overview of how to structure and write clear documentation. +- The [Strapi Documentation Style Guide](https://handbook.strapi.io/user-success-manual/strapi-documentation-style-guide) has formatting guidelines and how to implement formatting in markdown files. -Read the information below to know how your contribution will be handled by the Strapi Documentation team until it is merged and deployed. +When you are finished writing, create a pull request from your forked repository to the original `documentation` repository (see [the GitHub docs](https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork) for more information) or use the _Create a new branch for this commit and start a pull request_ option if you are using the GitHub web browser interface (see [the GitHub docs](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request)). -#### Handling +✋ Sign the CLA (Contributor License Agreement), directly via GitHub (see [our dedicated blog post](https://strapi.io/blog/switching-from-dco-to-cla) for more information). -When a new pull request is submitted in the Strapi `documentation` repository, it is handled in the following week, meaning that the Strapi team: +### Review and management of pull requests -- acknowledges the new pull request, leaving a 👀 reaction on the description -- tags the pull request, to indicate the type of documentation that is being updated, and optionally the level of priority for the contribution -- assigns the pull request to a member of the Strapi Documentation team, who will be in charge of the reviewing and merging +The pull request review process and timeline are based on the availability of Strapi's Documentation team to handle community contributions. The workflow is: -#### Review +1. The pull request is assigned to a member of the Documentation team. +2. At least 1 member of the Documentation team will review the pull request for: -Once all of the handling steps are done by the Strapi team, you can expect your pull request to be reviewed in the next week or so. +- accuracy, +- quality, +- alignment with the documentation scope and roadmap. -Here is what the Strapi Documentation team will review in your pull request: - -- The accuracy and coherence of the contribution, by testing any new piece of code or action for example, -- The quality of the technical writing, to make sure it is proper technical documentation that is easy to understand (see [12 Rules of Technical Writing](https://www.notion.so/12-Rules-of-Technical-Writing-c75e080e6b19432287b3dd61c2c9fa04)) -- The fit of the contribution among the rest of the Strapi documentation (see [Strapi Documentation Style Guide](https://www.notion.so/Strapi-Documentation-Style-Guide-b9c21387732741ed8b0a3f9701612577)) - -The pull request will be validated once the contribution ticks all the boxes. At least the validation of the Strapi Documentation team member in charge of the pull request is necessary for it to be merged. - -#### Deployment - -Once your pull request is validated and merged, it will be deployed with the next batch of merged pull requests. The Strapi Documentation team only deploys the documentation on Wednesdays, but not every week. +3. Reviewers will either approve, ask for changes, or reject the pull request. +4. Accepted pull requests will be merged and deployed as part of the regular documentation deployments on Wednesdays every 2 weeks. Every documentation deployment is communicated through a message in [the "News" section of the Strapi forum](https://forum.strapi.io/c/news/5). - - diff --git a/docs/.vuepress/config/theme-config.js b/docs/.vuepress/config/theme-config.js index b8f33817b9..84bc905631 100644 --- a/docs/.vuepress/config/theme-config.js +++ b/docs/.vuepress/config/theme-config.js @@ -1,5 +1,5 @@ const themeConfig = { - logo: '/assets/logo.svg', + logo: '/assets/logo.png', nav: [ { text: 'Resource Center', diff --git a/docs/.vuepress/public/assets/SearchIcon.png b/docs/.vuepress/public/assets/SearchIcon.png new file mode 100644 index 0000000000..7e2bc1b114 Binary files /dev/null and b/docs/.vuepress/public/assets/SearchIcon.png differ diff --git a/docs/.vuepress/styles/branding.styl b/docs/.vuepress/styles/branding.styl index 73e86877c9..0aa4860b30 100644 --- a/docs/.vuepress/styles/branding.styl +++ b/docs/.vuepress/styles/branding.styl @@ -1,4 +1,132 @@ body +// TODO: system fonts + font-family: system-ui + +.install-link + // text-decoration: none + background-color: #4945FF + border-radius: 6px + padding: 20px + color: $primary100 + justify-content: space-between + + .text + flex-grow: 1 + + .title + color: $neutral0 + + .description + color: $primary100 + + .arrow + width: 24px + height: 24px + + &:hover + .title + color: $neutral0 + text-decoration: underline + .description + color: $neutral0 + // text-decoration: none + .arrow + // TODO: + +#algolia-autocomplete-listbox-0 +#algolia-autocomplete-listbox-1 +#algolia-autocomplete-listbox-2 + left: 24px !important + +.search-box + display: inline-block + width: 20rem + margin: 0 !important + padding: 22px 0 20px 0 !important + text-align: center + + >span + display: inline-block + width: 100% + + .search-query + display: none + + #algolia-search-input + display: inline-block + width: calc(20rem - 90px) !important + height: 40px !important; + padding: 0 0 0 40px !important; + font-family: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, 'Open Sans', 'Helvetica Neue', sans-serif; + font-size: 13px !important; + color: $neutral600 !important + border-radius: 6px !important + border: 1px solid $neutral200 !important + background: #fff url(/assets/SearchIcon.png) 12px 12px no-repeat !important; + background-size: 16px 16px !important; + + &::-webkit-input-placeholder + color $neutral600 !important + &:-moz-placeholder /* Firefox 18- */ + color $neutral600 !important + &::-moz-placeholder /* Firefox 19+ */ + color $neutral600 !important + &:-ms-input-placeholder + color $neutral600 !important + +.theme-container + display: flex + flex-direction: column + height: 100% + +.algolia-autocomplete + &.algolia-autocomplete-left + &.ds-dropdown-menu + left: 24px !important + +.al +.algolia-search-wrapper + .algolia-autocomplete + .ds-dropdown-menu [class^=ds-dataset-] + padding: 0 + border: 1px solid $neutral150 + .ds-suggestions + margin-top: 0 + .ds-dropdown-menu + overflow: initial + margin: 10px 0 0 + box-shadow 0 1px 3px 1px rgba(0,0,0,.15) + &:before + background $neutral100 + border: 1px solid $neutral150 + box-shadow 0 1px 3px 1px $neutral150 + .ds-suggestion.ds-cursor + .algolia-docsearch-suggestion:not(.suggestion-layout-simple) + .algolia-docsearch-suggestion--content + background-color: $primary100 + .algolia-docsearch-suggestion + padding: 0 + .algolia-docsearch-suggestion--wrapper + padding: 0 0 0 16px + .algolia-docsearch-suggestion--category-header + margin: 0 + padding: 10px 16px 10px + color: $neutral900 !important + border-bottom: 1px solid $neutral150 !important + background: $neutral100 + .algolia-docsearch-suggestion--subcategory-column + color: $neutral600 !important + &:before + background $neutral150 + .algolia-docsearch-suggestion--title + padding-right: 16px + color $neutral900 !important + line-height 22px !important + .algolia-docsearch-suggestion--text + padding-right: 16px + color $neutral400 !important + .algolia-docsearch-footer + display: none !important font-family system-ui color $neutral800 diff --git a/docs/.vuepress/theme/components/AlgoliaSearchBox.vue b/docs/.vuepress/theme/components/AlgoliaSearchBox.vue index c1f46b2246..1262e803a8 100644 --- a/docs/.vuepress/theme/components/AlgoliaSearchBox.vue +++ b/docs/.vuepress/theme/components/AlgoliaSearchBox.vue @@ -7,7 +7,7 @@ @@ -17,7 +17,7 @@ export default { props: ['options'], data () { return { - placeholder: undefined + placeholder: 'undefined' } }, mounted () { @@ -26,27 +26,61 @@ export default { }, methods: { initialize (userOptions, config, lang) { + const self = this; + Promise.all([ import(/* webpackChunkName: "docsearch" */ 'docsearch.js/dist/cdn/docsearch.min.js'), import(/* webpackChunkName: "docsearch" */ 'docsearch.js/dist/cdn/docsearch.min.css') ]).then(([docsearch]) => { - docsearch = docsearch.default - const { algoliaOptions = {}} = userOptions + const sidebar = document.querySelector('.sidebar'); + const input = document.getElementById('algolia-search-input'); + + docsearch = docsearch.default; + + // Handle the edge case when the user remove their search manually. + input.addEventListener('keyup', () => { + if (input.value === null || input.value === '') { + sidebar.style.width = '20rem'; + } + }); + + // Handle the edge case when there is no results, and the user focus somewhere else. + input.addEventListener('focusout', () => { + sidebar.style.width = '20rem'; + }); + + const { algoliaOptions = {}} = userOptions; + docsearch(Object.assign( {}, + { + autocompleteOptions: { + debug: false + } + }, userOptions, { inputSelector: '#algolia-search-input', // #697 Make docsearch work well at i18n mode. algoliaOptions: Object.assign({ - 'facetFilters': [`lang:${lang}`].concat(algoliaOptions.facetFilters || []) + 'facetFilters': [`lang:${lang}`].concat(algoliaOptions.facetFilters || []), }, algoliaOptions), - handleSelected: (input, event, suggestion) => { - const { pathname, hash } = new URL(suggestion.url) + handleSelected: (input, event, suggestion, dataSetNumber, context) => { + const { pathname, hash } = new URL(suggestion.url); const removedBase = config.base ? '/' + pathname.replace(config.base, '') : pathname; - this.$router.push(`${removedBase}${hash}`) - } - } + + // Redirect to the resource + this.$router.push(`${removedBase}${hash}`); + + // Reset parameters for better UX + sidebar.style.width = '20rem'; + input.setVal(self.placeholder); + + }, + queryHook: function(query) { + sidebar.style.width = '40rem'; + }, + }, )) }) }, @@ -67,12 +101,12 @@ export default { \ No newline at end of file + diff --git a/docs/.vuepress/theme/components/Navbar.vue b/docs/.vuepress/theme/components/Navbar.vue index 04f5883067..7470168443 100644 --- a/docs/.vuepress/theme/components/Navbar.vue +++ b/docs/.vuepress/theme/components/Navbar.vue @@ -38,21 +38,16 @@ 'max-width': linksWrapMaxWidth + 'px' } : {}" > - + + diff --git a/docs/developer-docs/latest/developer-resources/database-apis-reference/entity-service/crud.md b/docs/developer-docs/latest/developer-resources/database-apis-reference/entity-service/crud.md index d6a540860c..488a908a9f 100644 --- a/docs/developer-docs/latest/developer-resources/database-apis-reference/entity-service/crud.md +++ b/docs/developer-docs/latest/developer-resources/database-apis-reference/entity-service/crud.md @@ -6,7 +6,7 @@ canonicalUrl: https://docs.strapi.io/developer-docs/latest/developer-resources/d # Entity Service API: CRUD operations -The [Entity Service API](/developer-docs/latest/developer-resources/database-apis-reference/entity-service-api.md) is built on top of the the [Query Engine API](/developer-docs/latest/developer-resources/database-apis-reference/entity-service-api.md) and uses it to perform CRUD operations on entities. +The [Entity Service API](/developer-docs/latest/developer-resources/database-apis-reference/entity-service-api.md) is built on top of the the [Query Engine API](/developer-docs/latest/developer-resources/database-apis-reference/query-engine-api.md) and uses it to perform CRUD operations on entities. ## findOne() diff --git a/docs/developer-docs/latest/development/custom-fields.md b/docs/developer-docs/latest/development/custom-fields.md index c9bac2d7ab..14a2d3f2ce 100644 --- a/docs/developer-docs/latest/development/custom-fields.md +++ b/docs/developer-docs/latest/development/custom-fields.md @@ -199,7 +199,7 @@ register(app) { ::: ::: tip -The `Input` React component receives several props. The [`ColorPickerInput` file](https://github.com/strapi/strapi/blob/features/custom-fields/packages/plugins/color-picker/admin/src/components/ColorPicker/ColorPickerInput/index.js#L10-L21) in the Strapi codebase gives you an example of how they can be used. +The `Input` React component receives several props. The [`ColorPickerInput` file](https://github.com/strapi/strapi/blob/main/packages/plugins/color-picker/admin/src/components/ColorPicker/ColorPickerInput/index.js#L71-L82) in the Strapi codebase gives you an example of how they can be used. ::: diff --git a/docs/developer-docs/latest/getting-started/introduction.md b/docs/developer-docs/latest/getting-started/introduction.md index a0bf5325a9..ac3e98f72b 100644 --- a/docs/developer-docs/latest/getting-started/introduction.md +++ b/docs/developer-docs/latest/getting-started/introduction.md @@ -23,7 +23,6 @@ As it goes hand in hand with the open-source ecosystem, Strapi is open to contri - [`strapi/strapi`](https://github.com/strapi/strapi): main repository of Strapi, which contains the core of the project. You can find the admin panel, core plugins, plugin providers, and the whole code that runs your Strapi application. Please read the [`CONTRIBUTING.md`](https://github.com/strapi/strapi/blob/master/CONTRIBUTING.md) file to have more information about contributions to the main repository. - [`strapi/documentation`](https://github.com/strapi/documentation): contains the whole documentation of Strapi. Please read the [contribution guide](https://github.com/strapi/documentation/blob/main/CONTRIBUTING.md) to have more information about contributions to the Strapi documentation. - [`strapi/design-system`](https://github.com/strapi/design-system): is the design system that is used in the admin panel. It brings consistency between the different admin plugins. -- [`strapi/strapi-docker`](https://github.com/strapi/strapi-docker): contains the code used to generate the official Docker images for Strapi (available through our [Docker Hub](https://hub.docker.com/r/strapi/strapi)). - [`strapi/awesome-strapi`](https://github.com/strapi/awesome-strapi): contains everything the community built and all managed plugins. It is used as a central place to find and submit new packages such as plugins, middlewares, hooks, and general enhancements to the core of Strapi. ## Strapi Community diff --git a/docs/developer-docs/latest/plugins/upload.md b/docs/developer-docs/latest/plugins/upload.md index 048e68b2e2..fa6b5cb2ad 100644 --- a/docs/developer-docs/latest/plugins/upload.md +++ b/docs/developer-docs/latest/plugins/upload.md @@ -142,12 +142,11 @@ In addition to the middleware configuration, you can pass the `sizeLimit`, which ```js -// path: ./config/middlewares.js +// path: ./config/plugins.js -export default { +module.exports = { // ... - { - name: "strapi::body", + upload: { config: { providerOptions: { sizeLimit: 250 * 1024 * 1024 // 256mb in bytes diff --git a/docs/developer-docs/latest/setup-deployment-guides/configurations/optional/sso.md b/docs/developer-docs/latest/setup-deployment-guides/configurations/optional/sso.md index aa810391a7..7f8e0d9853 100644 --- a/docs/developer-docs/latest/setup-deployment-guides/configurations/optional/sso.md +++ b/docs/developer-docs/latest/setup-deployment-guides/configurations/optional/sso.md @@ -207,7 +207,7 @@ module.exports = ({ env }) => ({ ```jsx // path: ./config/admin.ts -import GoogleStrategy from "passport-google-oauth2"; +import {Strategy as GoogleStrategy } from "passport-google-oauth2"; export default ({ env }) => ({ auth: { @@ -316,7 +316,7 @@ module.exports = ({ env }) => ({ ```jsx // path: ./config/admin.ts -import GithubStrategy from "passport-github2"; +import { Strategy as GithubStrategy } from "passport-github2"; export default ({ env }) => ({ auth: { @@ -428,7 +428,8 @@ module.exports = ({ env }) => ({ ```jsx // path: ./config/admin.ts -import DiscordStrategy from "passport-discord"; +import { Strategy as DiscordStrategy } from "passport-discord"; + export default ({ env }) => ({ auth: { @@ -544,7 +545,7 @@ module.exports = ({ env }) => ({ ```jsx // path: ./config/admin.ts -import AzureAdOAuth2Strategy from "passport-azure-ad-oauth2"; +import { Strategy as AzureAdOAuth2Strategy} from "passport-azure-ad-oauth2"; import jwt from "jsonwebtoken"; export default ({ env }) => ({ @@ -664,7 +665,7 @@ module.exports = ({ env }) => ({ ```jsx // path: ./config/admin.ts -import KeyCloakStrategy from "passport-keycloak-oauth2-oidc"; +import { Strategy as KeyCloakStrategy } from "passport-keycloak-oauth2-oidc"; export default ({ env }) => ({ auth: { @@ -774,7 +775,7 @@ module.exports = ({ env }) => ({ ```jsx // path: ./config/admin.ts -import { Strategy as OktaOAuth2Strategy } from "passport-okta-oauth20") +import { Strategy as OktaOAuth2Strategy } from "passport-okta-oauth20"; export default ({ env }) => ({ auth: { diff --git a/docs/developer-docs/latest/setup-deployment-guides/deployment/hosting-guides/amazon-aws.md b/docs/developer-docs/latest/setup-deployment-guides/deployment/hosting-guides/amazon-aws.md index 5881919f52..f6325cb880 100644 --- a/docs/developer-docs/latest/setup-deployment-guides/deployment/hosting-guides/amazon-aws.md +++ b/docs/developer-docs/latest/setup-deployment-guides/deployment/hosting-guides/amazon-aws.md @@ -436,6 +436,10 @@ git push You will next deploy your Strapi project to your EC2 instance by **cloning it from GitHub**. +::: note +Cloning a GitHub repository requires a personal access token. See the [GitHub documentation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) for how to generate and use a personal access token. +::: + From your terminal and logged into your EC2 instance as the `ubuntu` user: ```bash diff --git a/docs/developer-docs/latest/setup-deployment-guides/deployment/hosting-guides/heroku.md b/docs/developer-docs/latest/setup-deployment-guides/deployment/hosting-guides/heroku.md index cfcb8d4b28..2bd1c19136 100644 --- a/docs/developer-docs/latest/setup-deployment-guides/deployment/hosting-guides/heroku.md +++ b/docs/developer-docs/latest/setup-deployment-guides/deployment/hosting-guides/heroku.md @@ -415,6 +415,10 @@ git push heroku HEAD:main heroku open ``` +::: tip +If you see the following issue while running the `git push` command: `'heroku' does not appear to be a git repository`, run the following command: `heroku git:remote -a your-app-name`. +::: + ## File Uploads Like with project updates on Heroku, the file system doesn't support local uploading of files as they will be wiped when Heroku "cycles" the dyno. This type of file system is called [ephemeral](https://devcenter.heroku.com/articles/dynos#ephemeral-filesystem), which means the file system only lasts until the dyno is restarted (with Heroku this happens any time you redeploy or during their regular restart which can happen every few hours or every day). diff --git a/docs/developer-docs/latest/setup-deployment-guides/installation.md b/docs/developer-docs/latest/setup-deployment-guides/installation.md index 476543471c..d88ceac06b 100644 --- a/docs/developer-docs/latest/setup-deployment-guides/installation.md +++ b/docs/developer-docs/latest/setup-deployment-guides/installation.md @@ -39,7 +39,7 @@ Strapi projects and applications can be installed either locally on a computer o - \ No newline at end of file + diff --git a/docs/developer-docs/latest/setup-deployment-guides/installation/docker.md b/docs/developer-docs/latest/setup-deployment-guides/installation/docker.md index a6e43e833f..312550e49d 100644 --- a/docs/developer-docs/latest/setup-deployment-guides/installation/docker.md +++ b/docs/developer-docs/latest/setup-deployment-guides/installation/docker.md @@ -1,169 +1,464 @@ --- -title: Install from Docker - Strapi Developer Docs -description: Quickly create a Strapi application using our official Strapi Docker images. +title: Custom Docker Container - Strapi Developer Docs +description: Quickly create a Docker container from a local project. canonicalUrl: https://docs.strapi.io/developer-docs/latest/setup-deployment-guides/installation/docker.html --- -# Installing using Docker +# Running Strapi in a Docker container :::caution -This Docker image is only for Strapi v3. For now, Strapi will not update the image for v4. -However, to build an image compatible with Strapi v4, we recommend following [this guide](https://blog.dehlin.dev/docker-with-strapi-v4) by Simen Daehlin, Community Star at Strapi. +Strapi does not build any official container images. The following instructions are provided as a courtesy to the community. If you have any questions please reach out on [Discord](https://discord.strapi.io). +::: + +The following documentation will guide you through building a custom [Docker](https://www.docker.com/) container with an existing Strapi project. + +Docker is an open platform that allows developing, shipping, and running applications by using containers (i.e. packages containing all the parts an application needs to function, such as libraries and dependencies). Containers are isolated from each other and bundle their own software, libraries, and configuration files; they can communicate with each other through well-defined channels. -If you would like an official v4 image, please share it on the [roadmap](https://feedback.strapi.io/developer-experience). +::: prerequisites + +- [Docker](https://www.docker.com/) installed on your machine +- A [supported version of Node.js](/developer-docs/latest/setup-deployment-guides/installation/cli.md#step-1-make-sure-requirements-are-met) +- An existing Strapi v4 project, or a new one created with the [Quick Start guide](/developer-docs/latest/getting-started/quick-start.md) +- (_optional_) [Yarn](https://yarnpkg.com/) installed on your machine +- (_optional_) [Docker Compose](https://docs.docker.com/compose/) installed on your machine ::: -The following documentation will guide you through the installation of a new Strapi project using [Docker](https://www.docker.com/). +## Development and/or Staging environments + +For working with Strapi locally on your host machine you can use the [Dockerfile](https://docs.docker.com/engine/reference/builder/), and if needed the [docker-compose.yml](https://docs.docker.com/compose/compose-file/) can also be used to start up a database container. -Docker is an open platform that allows to develop, ship and run applications by using containers (i.e. packages containing all the parts an application needs to function, such as libraries and dependencies). +Both methods require an existing Strapi project or a new one created (see [Quick Start](/developer-docs/latest/getting-started/quick-start.md) guide). + +### Development Dockerfile + +The following `Dockerfile` can be used to build a non-production Docker image for a Strapi project. ::: note -You can find the official Docker image for Strapi in the [Docker Hub](https://hub.docker.com/r/strapi/strapi). +If you are using `docker-compose`, you can skip setting the environment variables manually, as they will be set in the `docker-compose.yml` file or a `.env` file. ::: -## Creating a Strapi project - -1. Create an empty folder. -2. In your empty folder, create a `docker-compose.yaml` file. It is where the new Strapi project will be created, and it defines the database and Strapi service to use. - - ::::: tabs card - - :::: tab SQLite - - ```yaml - version: '3' - services: - strapi: - image: strapi/strapi - volumes: - - ./app:/srv/app - ports: - - '1337:1337' - ``` - - :::: - - :::: tab PostgreSQL - - ```yaml - version: '3' - services: - strapi: - image: strapi/strapi - environment: - DATABASE_CLIENT: postgres - DATABASE_NAME: strapi - DATABASE_HOST: postgres - DATABASE_PORT: 5432 - DATABASE_USERNAME: strapi - DATABASE_PASSWORD: strapi - volumes: - - ./app:/srv/app - ports: - - '1337:1337' - depends_on: - - postgres - - postgres: - image: postgres - environment: - POSTGRES_DB: strapi - POSTGRES_USER: strapi - POSTGRES_PASSWORD: strapi - volumes: - - ./data:/var/lib/postgresql/data - ``` - - :::: - - :::: tab MySQL - - ```yaml - version: '3' - services: - strapi: - image: strapi/strapi - environment: - DATABASE_CLIENT: mysql - DATABASE_HOST: mysql - DATABASE_PORT: 3306 - DATABASE_NAME: strapi - DATABASE_USERNAME: strapi - DATABASE_PASSWORD: strapi - DATABASE_SSL: 'false' - volumes: - - ./app:/srv/app - ports: - - '1337:1337' - depends_on: - - mysql - - mysql: - image: mysql - command: mysqld --default-authentication-plugin=mysql_native_password - volumes: - - ./data:/var/lib/mysql - environment: - MYSQL_ROOT_PASSWORD: strapi - MYSQL_DATABASE: strapi - MYSQL_USER: strapi - MYSQL_PASSWORD: strapi - ``` - - :::: - - :::: tab MariaDB - - ```yaml - version: '3' - services: - strapi: - image: strapi/strapi - environment: - DATABASE_CLIENT: mysql - DATABASE_HOST: mariadb - DATABASE_PORT: 3306 - DATABASE_NAME: strapi - DATABASE_USERNAME: strapi - DATABASE_PASSWORD: strapi - DATABASE_SSL: 'false' - volumes: - - ./app:/srv/app - ports: - - '1337:1337' - depends_on: - - mariadb - - mariadb: - image: mariadb - volumes: - - ./data:/var/lib/mysql - environment: - MYSQL_ROOT_PASSWORD: strapi - MYSQL_DATABASE: strapi - MYSQL_USER: strapi - MYSQL_PASSWORD: strapi - ``` - - :::: - - ::::: - -3. Pull the latest images using the following command: - - ``` - docker-compose pull - ``` - -## Running Strapi - -To run your Strapi project created with Docker, use one of the following commands: +!!!include(developer-docs/latest/setup-deployment-guides/snippets/docker-env-table.md)!!! -```bash -# Execute Docker image detaching the terminal -docker-compose up -d +For more information on the `Dockerfile` and its commands, please refer to the [official Docker documentation](https://docs.docker.com/engine/reference/commandline/cli/). + +Sample `Dockerfile`: + + + + + +```Dockerfile +# path: ./Dockerfile + +FROM node:16-alpine +# Installing libvips-dev for sharp Compatibility +RUN apk update && apk add build-base gcc autoconf automake zlib-dev libpng-dev nasm bash vips-dev +ARG NODE_ENV=development +ENV NODE_ENV=${NODE_ENV} +WORKDIR /opt/ +COPY ./package.json ./yarn.lock ./ +ENV PATH /opt/node_modules/.bin:$PATH +RUN yarn config set network-timeout 600000 -g && yarn install +WORKDIR /opt/app +COPY ./ . +RUN yarn build +EXPOSE 1337 +CMD ["yarn", "develop"] +``` + + + + + +```Dockerfile +# path: ./Dockerfile + +FROM node:16-alpine +# Installing libvips-dev for sharp Compatibility +RUN apk update && apk add build-base gcc autoconf automake zlib-dev libpng-dev nasm bash vips-dev +ARG NODE_ENV=development +ENV NODE_ENV=${NODE_ENV} +WORKDIR /opt/ +COPY ./package.json ./package-lock.json ./ +ENV PATH /opt/node_modules/.bin:$PATH +RUN npm install +WORKDIR /opt/app +COPY ./ . +RUN npm run build +EXPOSE 1337 +CMD ["npm", "run", "develop"] +``` + + + + + +### (Optional) Docker Compose + +The following `docker-compose.yml` can be used to start up a database container and a Strapi container along with a shared network for communication between the two. + +::: note +For more information about running Docker compose and its commands, please refer to the [Docker Compose documentation](https://docs.docker.com/compose/). +::: + +Sample `docker-compose.yml`: + + + + + +```yml +# path: ./docker-compose.yml + +version: '3' +services: + strapi: + container_name: strapi + build: . + image: strapi:latest + restart: unless-stopped + env_file: .env + environment: + DATABASE_CLIENT: ${DATABASE_CLIENT} + DATABASE_HOST: strapiDB + DATABASE_PORT: ${DATABASE_PORT} + DATABASE_NAME: ${DATABASE_NAME} + DATABASE_USERNAME: ${DATABASE_USERNAME} + DATABASE_PASSWORD: ${DATABASE_PASSWORD} + JWT_SECRET: ${JWT_SECRET} + ADMIN_JWT_SECRET: ${ADMIN_JWT_SECRET} + APP_KEYS: ${APP_KEYS} + NODE_ENV: ${NODE_ENV} + volumes: + - ./config:/opt/app/config + - ./src:/opt/app/src + - ./package.json:/opt/package.json + - ./yarn.lock:/opt/yarn.lock + - ./.env:/opt/app/.env + - ./public/uploads:/opt/app/public/uploads + ports: + - '1337:1337' + networks: + - strapi + depends_on: + - strapiDB + + strapiDB: + container_name: strapiDB + platform: linux/amd64 #for platform error on Apple M1 chips + restart: unless-stopped + env_file: .env + image: mysql:5.7 + command: --default-authentication-plugin=mysql_native_password + environment: + MYSQL_USER: ${DATABASE_USERNAME} + MYSQL_ROOT_PASSWORD: ${DATABASE_PASSWORD} + MYSQL_PASSWORD: ${DATABASE_PASSWORD} + MYSQL_DATABASE: ${DATABASE_NAME} + volumes: + - strapi-data:/var/lib/mysql + #- ./data:/var/lib/mysql # if you want to use a bind folder + ports: + - '3306:3306' + networks: + - strapi + +volumes: + strapi-data: + +networks: + strapi: + name: Strapi + driver: bridge +``` + + + + + +```yml +# path: ./docker-compose.yml + +version: '3' +services: + strapi: + container_name: strapi + build: . + image: strapi:latest + restart: unless-stopped + env_file: .env + environment: + DATABASE_CLIENT: ${DATABASE_CLIENT} + DATABASE_HOST: strapiDB + DATABASE_PORT: ${DATABASE_PORT} + DATABASE_NAME: ${DATABASE_NAME} + DATABASE_USERNAME: ${DATABASE_USERNAME} + DATABASE_PASSWORD: ${DATABASE_PASSWORD} + JWT_SECRET: ${JWT_SECRET} + ADMIN_JWT_SECRET: ${ADMIN_JWT_SECRET} + APP_KEYS: ${APP_KEYS} + NODE_ENV: ${NODE_ENV} + volumes: + - ./config:/opt/app/config + - ./src:/opt/app/src + - ./package.json:/opt/package.json + - ./yarn.lock:/opt/yarn.lock + - ./.env:/opt/app/.env + - ./public/uploads:/opt/app/public/uploads + ports: + - '1337:1337' + networks: + - strapi + depends_on: + - strapiDB + + strapiDB: + container_name: strapiDB + platform: linux/amd64 #for platform error on Apple M1 chips + restart: unless-stopped + env_file: .env + image: mariadb:latest + environment: + MYSQL_USER: ${DATABASE_USERNAME} + MYSQL_ROOT_PASSWORD: ${DATABASE_PASSWORD} + MYSQL_PASSWORD: ${DATABASE_PASSWORD} + MYSQL_DATABASE: ${DATABASE_NAME} + volumes: + - strapi-data:/var/lib/mysql + #- ./data:/var/lib/mysql # if you want to use a bind folder + ports: + - '3306:3306' + networks: + - strapi + +volumes: + strapi-data: + +networks: + strapi: + name: Strapi + driver: bridge +``` + + + + + +```yml +# path: ./docker-compose.yml + +version: '3' +services: + strapi: + container_name: strapi + build: . + image: strapi:latest + restart: unless-stopped + env_file: .env + environment: + DATABASE_CLIENT: ${DATABASE_CLIENT} + DATABASE_HOST: strapiDB + DATABASE_PORT: ${DATABASE_PORT} + DATABASE_NAME: ${DATABASE_NAME} + DATABASE_USERNAME: ${DATABASE_USERNAME} + DATABASE_PASSWORD: ${DATABASE_PASSWORD} + JWT_SECRET: ${JWT_SECRET} + ADMIN_JWT_SECRET: ${ADMIN_JWT_SECRET} + APP_KEYS: ${APP_KEYS} + NODE_ENV: ${NODE_ENV} + volumes: + - ./config:/opt/app/config + - ./src:/opt/app/src + - ./package.json:/opt/package.json + - ./yarn.lock:/opt/yarn.lock + - ./.env:/opt/app/.env + - ./public/uploads:/opt/app/public/uploads + ports: + - '1337:1337' + networks: + - strapi + depends_on: + - strapiDB + + strapiDB: + container_name: strapiDB + platform: linux/amd64 #for platform error on Apple M1 chips + restart: unless-stopped + env_file: .env + image: postgres:12.0-alpine + environment: + POSTGRES_USER: ${DATABASE_USERNAME} + POSTGRES_PASSWORD: ${DATABASE_PASSWORD} + POSTGRES_DB: ${DATABASE_NAME} + volumes: + - strapi-data:/var/lib/postgresql/data/ #using a volume + #- ./data:/var/lib/postgresql/data/ # if you want to use a bind folder + + ports: + - '5432:5432' + networks: + - strapi + +volumes: + strapi-data: + +networks: + strapi: + name: Strapi + driver: bridge +``` + + + + + +## Production Environments + +The Docker image in production is different from the one used in development/staging environments because of the differences in the admin build process in addition to the command used to run the application. Typical production environments will use a reverse proxy to serve the application and the admin panel. The Docker image is built with the production build of the admin panel and the command used to run the application is `strapi start`. + +Once the [Dockerfile](#production-dockerfile) is created, the [production container](#building-the-production-container) can be built. Optionally, the container can be published to a [registry](#optional-publishing-the-container-to-a-registry) to make it available to the community. [Community tools](#community-tools) can help you +in the process of building a production Docker image and deploying it to a production environment. + +### Production Dockerfile + +The following `Dockerfile` can be used to build a production Docker image for a Strapi project. + + -# Execute Docker image without detaching the terminal -docker-compose up + + +```Dockerfile +# path: ./Dockerfile.prod + +FROM node:16-alpine as build +# Installing libvips-dev for sharp Compatibility +RUN apk update && apk add build-base gcc autoconf automake zlib-dev libpng-dev vips-dev && rm -rf /var/cache/apk/* > /dev/null 2>&1 +ARG NODE_ENV=production +ENV NODE_ENV=${NODE_ENV} +WORKDIR /opt/ +COPY ./package.json ./yarn.lock ./ +ENV PATH /opt/node_modules/.bin:$PATH +RUN yarn config set network-timeout 600000 -g && yarn install +WORKDIR /opt/app +COPY ./ . +RUN yarn build + + +FROM node:16-alpine +RUN apk add vips-dev +RUN rm -rf /var/cache/apk/* +ARG NODE_ENV=production +ENV NODE_ENV=${NODE_ENV} +WORKDIR /opt/app +COPY --from=build /opt/node_modules ./node_modules +ENV PATH /opt/node_modules/.bin:$PATH +COPY --from=build /opt/app ./ +EXPOSE 1337 +CMD ["yarn", "start"] +``` + + + + + +```Dockerfile +# path: ./Dockerfile.prod + +FROM node:16-alpine as build +# Installing libvips-dev for sharp Compatibility +RUN apk update && apk add build-base gcc autoconf automake zlib-dev libpng-dev vips-dev && rm -rf /var/cache/apk/* > /dev/null 2>&1 +ARG NODE_ENV=production +ENV NODE_ENV=${NODE_ENV} +WORKDIR /opt/ +COPY ./package.json ./package-lock.json ./ +ENV PATH /opt/node_modules/.bin:$PATH +RUN npm install --production +WORKDIR /opt/app +COPY ./ . +RUN npm run build + + +FROM node:16-alpine +# Installing libvips-dev for sharp Compatibility +RUN apk add vips-dev +RUN rm -rf /var/cache/apk/* +ARG NODE_ENV=production +ENV NODE_ENV=${NODE_ENV} +WORKDIR /opt/app +COPY --from=build /opt/node_modules ./node_modules +ENV PATH /opt/node_modules/.bin:$PATH +COPY --from=build /opt/app ./ +EXPOSE 1337 +CMD ["npm", "run","start"] ``` + + + + + +### Building the production container + +Building production Docker images can have several options. The following example uses the `docker build` command to build a production Docker image for a Strapi project. However, it is recommended you review the [Docker documentation](https://docs.docker.com/engine/reference/commandline/build/) for more information on building Docker images with more advanced options. + +To build a production Docker image for a Strapi project, run the following command: + +```bash +docker build \ + --build-arg NODE_ENV=production \ + # --build-arg STRAPI_URL=https://api.example.com \ # Uncomment to set the Strapi Server URL + -t mystrapiapp:latest \ # Replace with your image name + -f Dockerfile.prod . +``` + +### (Optional) Publishing the container to a registry + +After you have built a production Docker image for a Strapi project, you can publish the image to a Docker registry. Ideally for production usage this should be a private registry as your Docker image will contain sensitive information. + +Depending on your hosting provider you may need to use a different command to publish your image. It is recommended you review the [Docker documentation](https://docs.docker.com/engine/reference/commandline/push/) for more information on publishing Docker images with more advanced options. + +Some popular hosting providers are: + +- [AWS ECR](https://aws.amazon.com/ecr/) +- [Azure Container Registry](https://azure.microsoft.com/en-us/services/container-registry/) +- [GCP Container Registry](https://cloud.google.com/container-registry) +- [Digital Ocean Container Registry](https://www.digitalocean.com/products/container-registry/) +- [IBM Cloud Container Registry](https://www.ibm.com/cloud/container-registry) +- [GitHub Container Registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry) +- [Gitlab Container Registry](https://docs.gitlab.com/ee/user/packages/container_registry/) + +## Community tools + +Several community tools are available to assist you in deploying Strapi to various cloud providers and setting up Docker in a development or production environment. + +We strongly support our community efforts and encourage you to check out the following tools, please help support them by contributing to their development. + +If you would like to add your tool to this list, please open a pull request on the [Strapi documentation repository](https://github.com/strapi/documentation). + +### @strapi-community/dockerize + +The `@strapi-community/dockerize` package is a CLI tool that can be used to generate a `Dockerfile` and `docker-compose.yml` file for a Strapi project. + +To get started run `npx @strapi-community/dockerize@latest` within an existing Strapi project folder and follow the CLI prompts. + +For more information please see the official [GitHub repository](https://github.com/strapi-community/strapi-tool-dockerize) or the [npm package](https://www.npmjs.com/package/@strapi-community/dockerize). + +### @strapi-community/deployify + +The `@strapi-community/deployify` package is a CLI tool that can be used to deploy your application to various cloud providers and hosting services. Several of these also support deploying a Strapi project with a Docker container and will call on the `@strapi-community/dockerize` package to generate the required files if they don't already exist. + +To get started run `npx @strapi-community/deployify@latest` within an existing Strapi project folder and follow the CLI prompts. + +For more information please see the official [GitHub repository](https://github.com/strapi-community/strapi-tool-deployify) or the [npm package](https://www.npmjs.com/package/@strapi-community/deployify). + +## Docker FAQ + +### Why doesn't Strapi provide official Docker images? + +Strapi is a framework that can be used to build many different types of applications. As such, it is not possible to provide a single Docker image that can be used for all use cases. + +### Why do we have different Dockerfiles for development and production? + +The primary reason for various Docker images is due to the way our Admin panel is built. The Admin panel is built using React and is bundled into the Strapi application during the build process. This means that the Strapi backend is acting as a web server to serve the Admin panel and thus certain environment variables are statically compiled into the built Admin panel. + +It is generally considered a best practice with Strapi to build different Docker images for development and production environments. This is because the development environment is not optimized for performance and is not intended to be exposed to the public internet. diff --git a/docs/developer-docs/latest/setup-deployment-guides/snippets/docker-env-table.md b/docs/developer-docs/latest/setup-deployment-guides/snippets/docker-env-table.md new file mode 100644 index 0000000000..9bbe6dc9ab --- /dev/null +++ b/docs/developer-docs/latest/setup-deployment-guides/snippets/docker-env-table.md @@ -0,0 +1,16 @@ +The following environment variables are required in order to run Strapi in a Docker container: + +| Variable name | Description | +|---------------|-------------| +| `NODE_ENV` | The environment in which the application is running. | +| `DATABASE_CLIENT` | The database client to use. | +| `DATABASE_HOST` | The database host. | +| `DATABASE_PORT` | The database port. | +| `DATABASE_NAME` | The database name. | +| `DATABASE_USERNAME` | The database username. | +| `DATABASE_PASSWORD` | The database password. | +| `JWT_SECRET` | The secret used to sign the JWT for the Users-Permissions plugin. | +| `ADMIN_JWT_SECRET` | The secret used to sign the JWT for the Admin panel. | +| `APP_KEYS` | The secret keys used to sign the session cookies. | + +You can also set some [optional environment variables](/developer-docs/latest/setup-deployment-guides/configurations/optional/environment.md#strapi-s-environment-variables). diff --git a/docs/developer-docs/latest/update-migration-guides/update-version.md b/docs/developer-docs/latest/update-migration-guides/update-version.md index 16ea57a941..6457b8f643 100644 --- a/docs/developer-docs/latest/update-migration-guides/update-version.md +++ b/docs/developer-docs/latest/update-migration-guides/update-version.md @@ -28,9 +28,9 @@ Strapi periodically releases code improvements through upgrades. Upgrades contai { // ... "dependencies": { - "@strapi/strapi": "4.4.0", - "@strapi/plugin-users-permissions": "4.3.9", - "@strapi/plugin-i18n": "4.4.0", + "@strapi/strapi": "4.4.1", + "@strapi/plugin-users-permissions": "4.4.1", + "@strapi/plugin-i18n": "4.4.1", "better-sqlite3": "7.4.6" // ... }