From 04ca21cf51f3318a7c33058700e6ca3f20f99fed Mon Sep 17 00:00:00 2001 From: ayntk-ai <122374094+ayntk-ai@users.noreply.github.com> Date: Fri, 6 Sep 2024 18:47:56 +0200 Subject: [PATCH] Feat: New contributing section and new guides --- CONTRIBUTION.md | 47 ++++++++++ astro.config.mjs | 8 ++ package-lock.json | 73 +++++++++++---- package.json | 6 +- .../docs/knowledge-base/add-a-service.mdx | 61 ------------- .../contribute/add-a-service.mdx | 91 +++++++++++++++++++ .../contribute-to-coolify-documentation.mdx | 29 ++++++ .../contribute/contribute-to-coolify.mdx | 30 ++++++ .../docs/knowledge-base/docker/compose.mdx | 4 +- 9 files changed, 265 insertions(+), 84 deletions(-) create mode 100644 CONTRIBUTION.md delete mode 100644 src/content/docs/knowledge-base/add-a-service.mdx create mode 100644 src/content/docs/knowledge-base/contribute/add-a-service.mdx create mode 100644 src/content/docs/knowledge-base/contribute/contribute-to-coolify-documentation.mdx create mode 100644 src/content/docs/knowledge-base/contribute/contribute-to-coolify.mdx diff --git a/CONTRIBUTION.md b/CONTRIBUTION.md new file mode 100644 index 0000000..8b7ac53 --- /dev/null +++ b/CONTRIBUTION.md @@ -0,0 +1,47 @@ +# Setting up Astro with Extensions for local development + +Follow these steps to set up Astro with Starlight and additional extensions: + +1. **Install Node.js and npm** + + Ensure you have Node.js and npm installed on your system. You can download them from [nodejs.org](https://nodejs.org/). + +2. **Fork the documentation-coolify repository and open the folder in a code editor** + +3. **Install Astro and Starlight** + + Run the following command inside the local repository: + ``` + npm install astro @astrojs/starlight + ``` + +4. **Install additional Starlight extensions** + + Install the required Starlight extensions by running the following command inside the local repository: + ``` + npm install starlight-openapi starlight-image-zoom starlight-links-validator + ``` + +5. **Install the Astro and MDX VS Code extension (optional)** + + Install the Astro and MDX VS Code extension to get syntax highlighting and other useful features: + - [Astro](https://marketplace.visualstudio.com/items?itemName=astro-build.astro-vscode) + - [MDX](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) + +6. **Create your contribution** + + Eiter edit a markdown file in the `src/content/docs/` directory or create a new `.mdx` file in the `src/content/docs/` directory and start writing your docs article. + +7. **Run your Astro site** + + Start the development server by running the following command inside the local repository: + ``` + npm run dev + ``` + This will start a local server and give you a URL to preview your changes. + +8. **Create a Pull Request** + + Create a new pull request from your forked repository to the main documentation-coolify repository. + + diff --git a/astro.config.mjs b/astro.config.mjs index ee93534..3b693ea 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -57,6 +57,14 @@ export default defineConfig({ collapsed: false, items: [ { label: 'FAQ', link: '/knowledge-base/faq' }, + + { label: 'Contribute to Coolify', collapsed: true, items: [ + { label: 'Contribute to core Coolify', link: '/knowledge-base/contribute/contribute-to-coolify' }, + { label: 'Add a new service template to Coolify', link: '/knowledge-base/contribute/add-a-service' }, + { label: 'Contribute to the Coolify Documentation', link: '/knowledge-base/contribute/contribute-to-coolify-documentation' }, + ] + }, + { label: 'Self-hosted Instance', collapsed: true, items: [ { label: 'Monitoring', link: '/knowledge-base/monitoring' }, diff --git a/package-lock.json b/package-lock.json index 272f104..2a06f8b 100644 --- a/package-lock.json +++ b/package-lock.json @@ -9,9 +9,9 @@ "version": "0.0.1", "dependencies": { "@astrojs/sitemap": "^3.1.6", - "@astrojs/starlight": "^0.26.1", + "@astrojs/starlight": "^0.26.3", "@astrojs/starlight-tailwind": "^2.0.3", - "astro": "^4.10.2", + "astro": "^4.15.3", "sharp": "^0.32.5", "starlight-image-zoom": "^0.8.0", "starlight-links-validator": "^0.11.0", @@ -139,9 +139,10 @@ } }, "node_modules/@astrojs/starlight": { - "version": "0.26.1", - "resolved": "https://registry.npmjs.org/@astrojs/starlight/-/starlight-0.26.1.tgz", - "integrity": "sha512-0qNYWZJ+ZOdSfM7du6fGuwUhyTHtAeRIl0zYe+dF0TxDvcakplO1SYLbGGX6lEVYE3PdBne7dcJww85bXZJIIQ==", + "version": "0.26.3", + "resolved": "https://registry.npmjs.org/@astrojs/starlight/-/starlight-0.26.3.tgz", + "integrity": "sha512-U3rSNwr5cNvJVSPuSncduZ3ioKwNoMAZxYw/riuOfcJeT8DaJua3Uq+Z57vmhI1VxF19BZ1REQ0moUL6nhR8KQ==", + "license": "MIT", "dependencies": { "@astrojs/mdx": "^3.1.3", "@astrojs/sitemap": "^3.1.6", @@ -539,6 +540,7 @@ "cpu": [ "ppc64" ], + "license": "MIT", "optional": true, "os": [ "aix" @@ -554,6 +556,7 @@ "cpu": [ "arm" ], + "license": "MIT", "optional": true, "os": [ "android" @@ -569,6 +572,7 @@ "cpu": [ "arm64" ], + "license": "MIT", "optional": true, "os": [ "android" @@ -584,6 +588,7 @@ "cpu": [ "x64" ], + "license": "MIT", "optional": true, "os": [ "android" @@ -599,6 +604,7 @@ "cpu": [ "arm64" ], + "license": "MIT", "optional": true, "os": [ "darwin" @@ -614,6 +620,7 @@ "cpu": [ "x64" ], + "license": "MIT", "optional": true, "os": [ "darwin" @@ -629,6 +636,7 @@ "cpu": [ "arm64" ], + "license": "MIT", "optional": true, "os": [ "freebsd" @@ -644,6 +652,7 @@ "cpu": [ "x64" ], + "license": "MIT", "optional": true, "os": [ "freebsd" @@ -659,6 +668,7 @@ "cpu": [ "arm" ], + "license": "MIT", "optional": true, "os": [ "linux" @@ -674,6 +684,7 @@ "cpu": [ "arm64" ], + "license": "MIT", "optional": true, "os": [ "linux" @@ -689,6 +700,7 @@ "cpu": [ "ia32" ], + "license": "MIT", "optional": true, "os": [ "linux" @@ -704,6 +716,7 @@ "cpu": [ "loong64" ], + "license": "MIT", "optional": true, "os": [ "linux" @@ -719,6 +732,7 @@ "cpu": [ "mips64el" ], + "license": "MIT", "optional": true, "os": [ "linux" @@ -734,6 +748,7 @@ "cpu": [ "ppc64" ], + "license": "MIT", "optional": true, "os": [ "linux" @@ -749,6 +764,7 @@ "cpu": [ "riscv64" ], + "license": "MIT", "optional": true, "os": [ "linux" @@ -764,6 +780,7 @@ "cpu": [ "s390x" ], + "license": "MIT", "optional": true, "os": [ "linux" @@ -779,6 +796,7 @@ "cpu": [ "x64" ], + "license": "MIT", "optional": true, "os": [ "linux" @@ -794,6 +812,7 @@ "cpu": [ "x64" ], + "license": "MIT", "optional": true, "os": [ "netbsd" @@ -809,6 +828,7 @@ "cpu": [ "x64" ], + "license": "MIT", "optional": true, "os": [ "openbsd" @@ -824,6 +844,7 @@ "cpu": [ "x64" ], + "license": "MIT", "optional": true, "os": [ "sunos" @@ -839,6 +860,7 @@ "cpu": [ "arm64" ], + "license": "MIT", "optional": true, "os": [ "win32" @@ -854,6 +876,7 @@ "cpu": [ "ia32" ], + "license": "MIT", "optional": true, "os": [ "win32" @@ -869,6 +892,7 @@ "cpu": [ "x64" ], + "license": "MIT", "optional": true, "os": [ "win32" @@ -2155,9 +2179,10 @@ } }, "node_modules/astro": { - "version": "4.15.1", - "resolved": "https://registry.npmjs.org/astro/-/astro-4.15.1.tgz", - "integrity": "sha512-XvKZ2GaDbCsMfcJess4o+4D4cCKja45GJ/9o6EJ6n96xaen8HZMRoJn3YKL9TOjIrL2NuU4mBFMG2JivPJ0foA==", + "version": "4.15.3", + "resolved": "https://registry.npmjs.org/astro/-/astro-4.15.3.tgz", + "integrity": "sha512-zwO8H+vnNYbrdKz0Pkh2a4B/JK06JUvI18w+FxL3B5u4jqPB/SU+LH9XVUUWdNQsyJ/DBHKAf0LDK0RmwxXQEw==", + "license": "MIT", "dependencies": { "@astrojs/compiler": "^2.10.3", "@astrojs/internal-helpers": "0.4.1", @@ -2165,7 +2190,7 @@ "@astrojs/telemetry": "3.1.0", "@babel/core": "^7.25.2", "@babel/plugin-transform-react-jsx": "^7.25.2", - "@babel/types": "^7.25.4", + "@babel/types": "^7.25.6", "@oslojs/encoding": "^0.4.1", "@rollup/pluginutils": "^5.1.0", "@types/babel__core": "^7.20.5", @@ -2210,15 +2235,15 @@ "prompts": "^2.4.2", "rehype": "^13.0.1", "semver": "^7.6.3", - "shiki": "^1.14.1", + "shiki": "^1.16.1", "string-width": "^7.2.0", "strip-ansi": "^7.1.0", "tinyexec": "^0.3.0", - "tsconfck": "^3.1.1", + "tsconfck": "^3.1.3", "unist-util-visit": "^5.0.0", "vfile": "^6.0.3", "vite": "^5.4.2", - "vitefu": "^0.2.5", + "vitefu": "^1.0.2", "which-pm": "^3.0.0", "xxhash-wasm": "^1.0.2", "yargs-parser": "^21.1.1", @@ -3104,6 +3129,7 @@ "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.21.5.tgz", "integrity": "sha512-mg3OPMV4hXywwpoDxu3Qda5xCKQi+vCTZq8S9J/EpkhB2HzKXq4SNFZE3+NK93JYxc8VMSep+lOUSC/RVKaBqw==", "hasInstallScript": true, + "license": "MIT", "bin": { "esbuild": "bin/esbuild" }, @@ -6917,6 +6943,7 @@ "version": "0.8.0", "resolved": "https://registry.npmjs.org/starlight-image-zoom/-/starlight-image-zoom-0.8.0.tgz", "integrity": "sha512-+YDqCyihQescGs9hJoyTQt+KHEq9s6zIv8ksBMjPjwOrVicXtY0pM4hHj8yO1r2znud4gTytyGt25kAOmRyP9A==", + "license": "MIT", "dependencies": { "rehype-raw": "7.0.0", "unist-util-visit": "5.0.0", @@ -6933,6 +6960,7 @@ "version": "0.11.0", "resolved": "https://registry.npmjs.org/starlight-links-validator/-/starlight-links-validator-0.11.0.tgz", "integrity": "sha512-7mKiP0xAS8ItKy8QAIkmeNYbzI4w0WD0pOYoTPa1xMNbz+qYr/QWT+a40QO/Z2XYJLzzQn47yomupUfI89wheg==", + "license": "MIT", "dependencies": { "github-slugger": "2.0.0", "hast-util-from-html": "2.0.1", @@ -6983,6 +7011,7 @@ "version": "0.7.0", "resolved": "https://registry.npmjs.org/starlight-openapi/-/starlight-openapi-0.7.0.tgz", "integrity": "sha512-+aqVVqmoFZTb3ibXM6mfl3nmKY/bCZOn5+FTRzOGulEOtG4R8Y8NGwj9HN+6vxLZSPlAPfKwb3ipcAdDbVBuCg==", + "license": "MIT", "dependencies": { "@readme/openapi-parser": "2.5.0", "github-slugger": "2.0.0" @@ -7658,12 +7687,13 @@ } }, "node_modules/vite": { - "version": "5.4.2", - "resolved": "https://registry.npmjs.org/vite/-/vite-5.4.2.tgz", - "integrity": "sha512-dDrQTRHp5C1fTFzcSaMxjk6vdpKvT+2/mIdE07Gw2ykehT49O0z/VHS3zZ8iV/Gh8BJJKHWOe5RjaNrW5xf/GA==", + "version": "5.4.3", + "resolved": "https://registry.npmjs.org/vite/-/vite-5.4.3.tgz", + "integrity": "sha512-IH+nl64eq9lJjFqU+/yrRnrHPVTlgy42/+IzbOdaFDVlyLgI/wDlf+FCobXLX1cT0X5+7LMyH1mIy2xJdLfo8Q==", + "license": "MIT", "dependencies": { "esbuild": "^0.21.3", - "postcss": "^8.4.41", + "postcss": "^8.4.43", "rollup": "^4.20.0" }, "bin": { @@ -7716,9 +7746,14 @@ } }, "node_modules/vitefu": { - "version": "0.2.5", - "resolved": "https://registry.npmjs.org/vitefu/-/vitefu-0.2.5.tgz", - "integrity": "sha512-SgHtMLoqaeeGnd2evZ849ZbACbnwQCIwRH57t18FxcXoZop0uQu0uzlIhJBlF/eWVzuce0sHeqPcDo+evVcg8Q==", + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/vitefu/-/vitefu-1.0.2.tgz", + "integrity": "sha512-0/iAvbXyM3RiPPJ4lyD4w6Mjgtf4ejTK6TPvTNG3H32PLwuT0N/ZjJLiXug7ETE/LWtTeHw9WRv7uX/tIKYyKg==", + "license": "MIT", + "workspaces": [ + "tests/deps/*", + "tests/projects/*" + ], "peerDependencies": { "vite": "^3.0.0 || ^4.0.0 || ^5.0.0" }, diff --git a/package.json b/package.json index 96acda8..de1bacb 100644 --- a/package.json +++ b/package.json @@ -3,7 +3,7 @@ "type": "module", "version": "0.0.1", "scripts": { - "dev": "astro dev", + "dev": "npx astro dev", "start": "astro dev", "build": "astro build", "preview": "astro preview", @@ -11,9 +11,9 @@ }, "dependencies": { "@astrojs/sitemap": "^3.1.6", - "@astrojs/starlight": "^0.26.1", + "@astrojs/starlight": "^0.26.3", "@astrojs/starlight-tailwind": "^2.0.3", - "astro": "^4.10.2", + "astro": "^4.15.3", "sharp": "^0.32.5", "starlight-image-zoom": "^0.8.0", "starlight-links-validator": "^0.11.0", diff --git a/src/content/docs/knowledge-base/add-a-service.mdx b/src/content/docs/knowledge-base/add-a-service.mdx deleted file mode 100644 index 4671586..0000000 --- a/src/content/docs/knowledge-base/add-a-service.mdx +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: "Add a service" -head: - - tag: "meta" - attrs: - property: "og:title" - content: "How to add a new service to Coolify" -description: "Here you can find the documentation for adding new services to Coolify." ---- - -import { Aside } from '@astrojs/starlight/components'; - -Services in Coolify are templates made from normal [docker-compose](https://docs.docker.com/reference/compose-file/) files + a bit of magic. -See [Coolify's docker-compose specs](/docs/knowledge-base/docker/compose) to learn how to benefit from generated variables and storage handling. - -## Metadata - -You need to add extra metadata to the top of the `docker-compose` file, like: - -- documentation link -- a slogan -- additional tags (for better searching) -- logo (local icon, could be svg, png, etc) -- port (always use the port which is the main entrypoint - like frontend - of the service) - - - -Example: - -``` -# documentation: https://docs.n8n.io/hosting/ -# slogan: n8n is an extendable workflow automation tool which enables you to connect anything to everything via its open, fair-code model. -# tags: n8n,workflow,automation,open,source,low,code -# logo: svgs/n8n.svg -# port: 5678 - -... rest of the compose file ... - -``` - -## Add a new service - -Official templates stored [here](https://github.com/coollabsio/coolify/blob/main/templates/compose). They are just normal docker-compose files with a bit of magic. - -To add a new service, you can easily test your templates with `Docker Compose` deployments inside Coolify. It uses the same process to parse, generate and deploy as the one-click services. - -If you are done with tests and everything works, open a [PR](https://github.com/coollabsio/coolify/compare), that have the new `.yaml` compose file under `/templates/compose`. - - - -### Request a new service - -If there is a service template you'd like to see: -1. Search GitHub discussions [here](https://github.com/coollabsio/coolify/discussions/categories/new-service-integrations). -2. If it has already been requested, upvote it. If not, create a new request. \ No newline at end of file diff --git a/src/content/docs/knowledge-base/contribute/add-a-service.mdx b/src/content/docs/knowledge-base/contribute/add-a-service.mdx new file mode 100644 index 0000000..0b2d30f --- /dev/null +++ b/src/content/docs/knowledge-base/contribute/add-a-service.mdx @@ -0,0 +1,91 @@ +--- +title: "Add a new service template to Coolify" +head: + - tag: "meta" + attrs: + property: "og:title" + content: "How to add a new service template to Coolify" +description: "Step-by-step guide on adding new service templates to Coolify." +--- + +import { Aside, Steps } from '@astrojs/starlight/components'; + +Services in Coolify are templates made from normal [docker-compose](https://docs.docker.com/reference/compose-file/) files with some added Coolify magic. + + + + + +1. Add metadata + + At the top of your `docker-compose` file, add the following metadata: + + ```yaml + # documentation: https://docs.example.com/ + # slogan: A brief description of your service. + # tags: tag1,tag2,tag3 + # logo: svgs/your-service.svg + # port: 1234 + ``` + + - `documentation`: Link to the service's official documentation + - `slogan`: A short description of the service + - `tags`: Comma-separated list for better searchability + - `logo`: Path to the service's logo (see step 3) + - `port`: The main entrypoint port of the service + + + +2. Create the docker-compose file + + Below the metadata, add your docker-compose configuration. Use Coolify's environment variable magic [here](/docs/knowledge-base/docker/compose#coolifys-magic-environment-variables). + + Example: + + ```yaml + version: '3.8' + services: + app: + image: your-service-image:tag + environment: + - DATABASE_URL=${COOLIFY_DATABASE_URL} + volumes: + - ${COOLIFY_VOLUME_APP}:/data + ``` + +3. Add a logo + + - Create or obtain an SVG logo for your service (strongly preferred format) + - If SVG is unavailable, use a high-quality PNG or JPG as a last resort + - Add the logo file to the `svgs` folder in the Coolify repository + - The logo filename should match the docker-compose service name exactly + - For example, if your service name is `wordpress`, your logo should be `wordpress.svg` and the final path then is `svgs/wordpress.svg` use this path in the `logo` metadata. + + +4. Test your template + + Use the `Docker Compose` deployment option in Coolify to test your template. This process mimics the one-click service deployment. + +5. Submit a Pull Request + + Once your template works correctly: + - Open a [PR](https://github.com/coollabsio/coolify/compare) + - Add your new `.yaml` compose file under `/templates/compose` + - Include the logo file in the `svgs` folder + + + + + +## Request a new service + +If there's a service template you'd like to see in Coolify: + +1. Search [GitHub discussions](https://github.com/coollabsio/coolify/discussions/categories/new-service-integrations) for existing requests. +2. If the service has been requested, upvote it. If not, create a new request. \ No newline at end of file diff --git a/src/content/docs/knowledge-base/contribute/contribute-to-coolify-documentation.mdx b/src/content/docs/knowledge-base/contribute/contribute-to-coolify-documentation.mdx new file mode 100644 index 0000000..291781a --- /dev/null +++ b/src/content/docs/knowledge-base/contribute/contribute-to-coolify-documentation.mdx @@ -0,0 +1,29 @@ +--- +title: "Contributing to Coolify Documentation" +head: + - tag: "meta" + attrs: + property: "og:title" + content: "How to contribute to Coolify Documentation" +description: "A guide on how to contribute to the Coolify documentation project." +--- + +import { Aside, LinkButton } from '@astrojs/starlight/components'; + +We appreciate your interest in contributing to the Coolify documentation! Your contributions help improve the documentation for all users. Before you begin, please take a moment to review our documentation contributing guide. + +## Documentation Contributing Guide + +For detailed information on how to contribute to the Coolify documentation, please refer to our official contributing guide: + + +Coolify Documentation Contributing Guide + + + \ No newline at end of file diff --git a/src/content/docs/knowledge-base/contribute/contribute-to-coolify.mdx b/src/content/docs/knowledge-base/contribute/contribute-to-coolify.mdx new file mode 100644 index 0000000..5220750 --- /dev/null +++ b/src/content/docs/knowledge-base/contribute/contribute-to-coolify.mdx @@ -0,0 +1,30 @@ +--- +title: "Contributing to core Coolify" +head: + - tag: "meta" + attrs: + property: "og:title" + content: "How to contribute to Coolify" +description: "A guide on how to contribute to the core Coolify project." +--- + +import { Aside, LinkButton } from '@astrojs/starlight/components'; + +We're thrilled that you're interested in contributing to Coolify! Thank you for your time and effort. Your contributions will be part of making Coolify better for everyone. Before you get started, please take a moment to review our comprehensive contributing guide. + +## Contributing Guide + +For detailed information on how to contribute to Coolify, please refer to our official contributing guide: + + +Coolify Contributing Guide + + + + \ No newline at end of file diff --git a/src/content/docs/knowledge-base/docker/compose.mdx b/src/content/docs/knowledge-base/docker/compose.mdx index feb1349..1437ed0 100644 --- a/src/content/docs/knowledge-base/docker/compose.mdx +++ b/src/content/docs/knowledge-base/docker/compose.mdx @@ -29,7 +29,9 @@ services: ![Coolify's UI for environment variables](../../../../assets/images/screenshots/Docker-compose-environment-variables-UI.png) -Additionally, Coolify can generate some dynamic variables for you. +## Coolify's Magic environment variables + +Additionally, Coolify can generate some dynamic environment variables for you. The syntax is `SERVICE__`. Type may be one of: