From ee37ebc4112295e853c71430fc7affe57905d935 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Mon, 16 Jun 2025 15:59:23 +0000 Subject: [PATCH 01/17] build(deps): bump fumadocs-ui from 15.5.1 to 15.5.3 Bumps [fumadocs-ui](https://github.com/fuma-nama/fumadocs) from 15.5.1 to 15.5.3. - [Release notes](https://github.com/fuma-nama/fumadocs/releases) - [Commits](https://github.com/fuma-nama/fumadocs/compare/fumadocs-ui@15.5.1...fumadocs-ui@15.5.3) --- updated-dependencies: - dependency-name: fumadocs-ui dependency-version: 15.5.3 dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] --- package-lock.json | 105 ++++++++++++++++++++++++++++++++++++++-------- package.json | 2 +- 2 files changed, 89 insertions(+), 18 deletions(-) diff --git a/package-lock.json b/package-lock.json index 4cf95bc..8d882b2 100644 --- a/package-lock.json +++ b/package-lock.json @@ -12,7 +12,7 @@ "@types/mdx": "^2.0.13", "fumadocs-core": "^15.5.1", "fumadocs-mdx": "^11.6.7", - "fumadocs-ui": "^15.5.1", + "fumadocs-ui": "^15.5.3", "lucide-react": "^0.513.0", "mdx": "^0.3.1", "next": "^15.3.3", @@ -2816,6 +2816,66 @@ "node": ">=14.0.0" } }, + "node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@emnapi/core": { + "version": "1.4.3", + "dev": true, + "inBundle": true, + "license": "MIT", + "optional": true, + "dependencies": { + "@emnapi/wasi-threads": "1.0.2", + "tslib": "^2.4.0" + } + }, + "node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@emnapi/runtime": { + "version": "1.4.3", + "dev": true, + "inBundle": true, + "license": "MIT", + "optional": true, + "dependencies": { + "tslib": "^2.4.0" + } + }, + "node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@emnapi/wasi-threads": { + "version": "1.0.2", + "dev": true, + "inBundle": true, + "license": "MIT", + "optional": true, + "dependencies": { + "tslib": "^2.4.0" + } + }, + "node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@napi-rs/wasm-runtime": { + "version": "0.2.10", + "dev": true, + "inBundle": true, + "license": "MIT", + "optional": true, + "dependencies": { + "@emnapi/core": "^1.4.3", + "@emnapi/runtime": "^1.4.3", + "@tybys/wasm-util": "^0.9.0" + } + }, + "node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@tybys/wasm-util": { + "version": "0.9.0", + "dev": true, + "inBundle": true, + "license": "MIT", + "optional": true, + "dependencies": { + "tslib": "^2.4.0" + } + }, + "node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/tslib": { + "version": "2.8.0", + "dev": true, + "inBundle": true, + "license": "0BSD", + "optional": true + }, "node_modules/@tailwindcss/oxide-win32-arm64-msvc": { "version": "4.1.8", "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-win32-arm64-msvc/-/oxide-win32-arm64-msvc-4.1.8.tgz", @@ -4954,30 +5014,31 @@ } }, "node_modules/fumadocs-core": { - "version": "15.5.1", - "resolved": "https://registry.npmjs.org/fumadocs-core/-/fumadocs-core-15.5.1.tgz", - "integrity": "sha512-5eJPJw+BFWFdgrtWPQ9aAZAhhsyuZAwth8OjBd9R77sXoIoae4Y4lJZMq3BeSpJZcuIAOVbSCS+pJhsBAoXJ8g==", + "version": "15.5.3", + "resolved": "https://registry.npmjs.org/fumadocs-core/-/fumadocs-core-15.5.3.tgz", + "integrity": "sha512-FGOrPqUpovSkc25s7EzNvYO0Oi1mlAJz9GxJ3jb8W1v5rmtWgjVhpjs5vBNMQtKDpQuO0GjkHN5iMQVbW0DvjQ==", "license": "MIT", "dependencies": { "@formatjs/intl-localematcher": "^0.6.1", "@orama/orama": "^3.1.6", - "@shikijs/rehype": "^3.4.2", - "@shikijs/transformers": "^3.4.2", + "@shikijs/rehype": "^3.6.0", + "@shikijs/transformers": "^3.6.0", "github-slugger": "^2.0.0", "hast-util-to-estree": "^3.1.3", "hast-util-to-jsx-runtime": "^2.3.6", "image-size": "^2.0.2", "negotiator": "^1.0.0", - "react-remove-scroll": "^2.6.3", + "react-remove-scroll": "^2.7.1", "remark": "^15.0.0", "remark-gfm": "^4.0.1", "remark-rehype": "^11.1.2", "scroll-into-view-if-needed": "^3.1.0", - "shiki": "^3.4.2", + "shiki": "^3.6.0", "unist-util-visit": "^5.0.0" }, "peerDependencies": { "@oramacloud/client": "1.x.x || 2.x.x", + "@types/react": "*", "algoliasearch": "5.x.x", "next": "14.x.x || 15.x.x", "react": "18.x.x || 19.x.x", @@ -4987,6 +5048,9 @@ "@oramacloud/client": { "optional": true }, + "@types/react": { + "optional": true + }, "algoliasearch": { "optional": true }, @@ -5045,9 +5109,9 @@ } }, "node_modules/fumadocs-ui": { - "version": "15.5.1", - "resolved": "https://registry.npmjs.org/fumadocs-ui/-/fumadocs-ui-15.5.1.tgz", - "integrity": "sha512-HyMoM+mv5WZrXDAv88SLLqFrduDSxQHFU+uQkSpJQdycaGNSIB8063PW/wb/QIliusWP8o+c/YLFy/29KymEWA==", + "version": "15.5.3", + "resolved": "https://registry.npmjs.org/fumadocs-ui/-/fumadocs-ui-15.5.3.tgz", + "integrity": "sha512-5SmN1j7HBQ9XuboAicfFqoNLPpN37Iwz0+cCLt6cOOequurTjfPfYCjvlKzP5q0GxDjrpU2vEQX/9JMa25bC6w==", "license": "MIT", "dependencies": { "@radix-ui/react-accordion": "^1.2.11", @@ -5061,21 +5125,28 @@ "@radix-ui/react-slot": "^1.2.3", "@radix-ui/react-tabs": "^1.1.12", "class-variance-authority": "^0.7.1", - "fumadocs-core": "15.5.1", + "fumadocs-core": "15.5.3", "lodash.merge": "^4.6.2", "next-themes": "^0.4.6", "postcss-selector-parser": "^7.1.0", "react-medium-image-zoom": "^5.2.14", - "react-remove-scroll": "^2.6.3", - "tailwind-merge": "^3.3.0" + "react-remove-scroll": "^2.7.1", + "tailwind-merge": "^3.3.1" }, "peerDependencies": { + "@types/react": "*", "next": "14.x.x || 15.x.x", "react": "18.x.x || 19.x.x", "react-dom": "18.x.x || 19.x.x", "tailwindcss": "^3.4.14 || ^4.0.0" }, "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "next": { + "optional": true + }, "tailwindcss": { "optional": true } @@ -13015,9 +13086,9 @@ } }, "node_modules/tailwind-merge": { - "version": "3.3.0", - "resolved": "https://registry.npmjs.org/tailwind-merge/-/tailwind-merge-3.3.0.tgz", - "integrity": "sha512-fyW/pEfcQSiigd5SNn0nApUOxx0zB/dm6UDU/rEwc2c3sX2smWUNbapHv+QRqLGVp9GWX3THIa7MUGPo+YkDzQ==", + "version": "3.3.1", + "resolved": "https://registry.npmjs.org/tailwind-merge/-/tailwind-merge-3.3.1.tgz", + "integrity": "sha512-gBXpgUm/3rp1lMZZrM/w7D8GKqshif0zAymAhbCyIt8KMe+0v9DQ7cdYLR4FHH/cKpdTXb+A/tKKU3eolfsI+g==", "license": "MIT", "funding": { "type": "github", diff --git a/package.json b/package.json index 354b893..e2c3e83 100644 --- a/package.json +++ b/package.json @@ -17,7 +17,7 @@ "@types/mdx": "^2.0.13", "fumadocs-core": "^15.5.1", "fumadocs-mdx": "^11.6.7", - "fumadocs-ui": "^15.5.1", + "fumadocs-ui": "^15.5.3", "lucide-react": "^0.513.0", "mdx": "^0.3.1", "next": "^15.3.3", From c9a16e5e952902dfd69e88e1393b51ce17d17a0a Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Mon, 16 Jun 2025 16:10:58 +0000 Subject: [PATCH 02/17] build(deps): bump fumadocs-core from 15.5.1 to 15.5.3 Bumps [fumadocs-core](https://github.com/fuma-nama/fumadocs) from 15.5.1 to 15.5.3. - [Release notes](https://github.com/fuma-nama/fumadocs/releases) - [Commits](https://github.com/fuma-nama/fumadocs/compare/fumadocs-core@15.5.1...fumadocs-core@15.5.3) --- updated-dependencies: - dependency-name: fumadocs-core dependency-version: 15.5.3 dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] --- package-lock.json | 128 +++++++++++++++++++++++++++++++++++++++++++--- package.json | 2 +- 2 files changed, 121 insertions(+), 9 deletions(-) diff --git a/package-lock.json b/package-lock.json index 4cf95bc..abb8348 100644 --- a/package-lock.json +++ b/package-lock.json @@ -10,7 +10,7 @@ "hasInstallScript": true, "dependencies": { "@types/mdx": "^2.0.13", - "fumadocs-core": "^15.5.1", + "fumadocs-core": "^15.5.3", "fumadocs-mdx": "^11.6.7", "fumadocs-ui": "^15.5.1", "lucide-react": "^0.513.0", @@ -2816,6 +2816,66 @@ "node": ">=14.0.0" } }, + "node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@emnapi/core": { + "version": "1.4.3", + "dev": true, + "inBundle": true, + "license": "MIT", + "optional": true, + "dependencies": { + "@emnapi/wasi-threads": "1.0.2", + "tslib": "^2.4.0" + } + }, + "node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@emnapi/runtime": { + "version": "1.4.3", + "dev": true, + "inBundle": true, + "license": "MIT", + "optional": true, + "dependencies": { + "tslib": "^2.4.0" + } + }, + "node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@emnapi/wasi-threads": { + "version": "1.0.2", + "dev": true, + "inBundle": true, + "license": "MIT", + "optional": true, + "dependencies": { + "tslib": "^2.4.0" + } + }, + "node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@napi-rs/wasm-runtime": { + "version": "0.2.10", + "dev": true, + "inBundle": true, + "license": "MIT", + "optional": true, + "dependencies": { + "@emnapi/core": "^1.4.3", + "@emnapi/runtime": "^1.4.3", + "@tybys/wasm-util": "^0.9.0" + } + }, + "node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@tybys/wasm-util": { + "version": "0.9.0", + "dev": true, + "inBundle": true, + "license": "MIT", + "optional": true, + "dependencies": { + "tslib": "^2.4.0" + } + }, + "node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/tslib": { + "version": "2.8.0", + "dev": true, + "inBundle": true, + "license": "0BSD", + "optional": true + }, "node_modules/@tailwindcss/oxide-win32-arm64-msvc": { "version": "4.1.8", "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-win32-arm64-msvc/-/oxide-win32-arm64-msvc-4.1.8.tgz", @@ -4954,30 +5014,31 @@ } }, "node_modules/fumadocs-core": { - "version": "15.5.1", - "resolved": "https://registry.npmjs.org/fumadocs-core/-/fumadocs-core-15.5.1.tgz", - "integrity": "sha512-5eJPJw+BFWFdgrtWPQ9aAZAhhsyuZAwth8OjBd9R77sXoIoae4Y4lJZMq3BeSpJZcuIAOVbSCS+pJhsBAoXJ8g==", + "version": "15.5.3", + "resolved": "https://registry.npmjs.org/fumadocs-core/-/fumadocs-core-15.5.3.tgz", + "integrity": "sha512-FGOrPqUpovSkc25s7EzNvYO0Oi1mlAJz9GxJ3jb8W1v5rmtWgjVhpjs5vBNMQtKDpQuO0GjkHN5iMQVbW0DvjQ==", "license": "MIT", "dependencies": { "@formatjs/intl-localematcher": "^0.6.1", "@orama/orama": "^3.1.6", - "@shikijs/rehype": "^3.4.2", - "@shikijs/transformers": "^3.4.2", + "@shikijs/rehype": "^3.6.0", + "@shikijs/transformers": "^3.6.0", "github-slugger": "^2.0.0", "hast-util-to-estree": "^3.1.3", "hast-util-to-jsx-runtime": "^2.3.6", "image-size": "^2.0.2", "negotiator": "^1.0.0", - "react-remove-scroll": "^2.6.3", + "react-remove-scroll": "^2.7.1", "remark": "^15.0.0", "remark-gfm": "^4.0.1", "remark-rehype": "^11.1.2", "scroll-into-view-if-needed": "^3.1.0", - "shiki": "^3.4.2", + "shiki": "^3.6.0", "unist-util-visit": "^5.0.0" }, "peerDependencies": { "@oramacloud/client": "1.x.x || 2.x.x", + "@types/react": "*", "algoliasearch": "5.x.x", "next": "14.x.x || 15.x.x", "react": "18.x.x || 19.x.x", @@ -4987,6 +5048,9 @@ "@oramacloud/client": { "optional": true }, + "@types/react": { + "optional": true + }, "algoliasearch": { "optional": true }, @@ -5081,6 +5145,54 @@ } } }, + "node_modules/fumadocs-ui/node_modules/fumadocs-core": { + "version": "15.5.1", + "resolved": "https://registry.npmjs.org/fumadocs-core/-/fumadocs-core-15.5.1.tgz", + "integrity": "sha512-5eJPJw+BFWFdgrtWPQ9aAZAhhsyuZAwth8OjBd9R77sXoIoae4Y4lJZMq3BeSpJZcuIAOVbSCS+pJhsBAoXJ8g==", + "license": "MIT", + "dependencies": { + "@formatjs/intl-localematcher": "^0.6.1", + "@orama/orama": "^3.1.6", + "@shikijs/rehype": "^3.4.2", + "@shikijs/transformers": "^3.4.2", + "github-slugger": "^2.0.0", + "hast-util-to-estree": "^3.1.3", + "hast-util-to-jsx-runtime": "^2.3.6", + "image-size": "^2.0.2", + "negotiator": "^1.0.0", + "react-remove-scroll": "^2.6.3", + "remark": "^15.0.0", + "remark-gfm": "^4.0.1", + "remark-rehype": "^11.1.2", + "scroll-into-view-if-needed": "^3.1.0", + "shiki": "^3.4.2", + "unist-util-visit": "^5.0.0" + }, + "peerDependencies": { + "@oramacloud/client": "1.x.x || 2.x.x", + "algoliasearch": "5.x.x", + "next": "14.x.x || 15.x.x", + "react": "18.x.x || 19.x.x", + "react-dom": "18.x.x || 19.x.x" + }, + "peerDependenciesMeta": { + "@oramacloud/client": { + "optional": true + }, + "algoliasearch": { + "optional": true + }, + "next": { + "optional": true + }, + "react": { + "optional": true + }, + "react-dom": { + "optional": true + } + } + }, "node_modules/function-bind": { "version": "1.1.2", "resolved": "https://registry.npmjs.org/function-bind/-/function-bind-1.1.2.tgz", diff --git a/package.json b/package.json index 354b893..9565686 100644 --- a/package.json +++ b/package.json @@ -15,7 +15,7 @@ }, "dependencies": { "@types/mdx": "^2.0.13", - "fumadocs-core": "^15.5.1", + "fumadocs-core": "^15.5.3", "fumadocs-mdx": "^11.6.7", "fumadocs-ui": "^15.5.1", "lucide-react": "^0.513.0", From eeb8fd096f853c3c59a1aa74dff0eaaa675cb582 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Mon, 16 Jun 2025 16:11:26 +0000 Subject: [PATCH 03/17] build(deps-dev): bump @tailwindcss/postcss from 4.1.8 to 4.1.10 Bumps [@tailwindcss/postcss](https://github.com/tailwindlabs/tailwindcss/tree/HEAD/packages/@tailwindcss-postcss) from 4.1.8 to 4.1.10. - [Release notes](https://github.com/tailwindlabs/tailwindcss/releases) - [Changelog](https://github.com/tailwindlabs/tailwindcss/blob/main/CHANGELOG.md) - [Commits](https://github.com/tailwindlabs/tailwindcss/commits/v4.1.10/packages/@tailwindcss-postcss) --- updated-dependencies: - dependency-name: "@tailwindcss/postcss" dependency-version: 4.1.10 dependency-type: direct:development update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] --- package-lock.json | 190 ++++++++++++++++++++++++++++++---------------- package.json | 2 +- 2 files changed, 126 insertions(+), 66 deletions(-) diff --git a/package-lock.json b/package-lock.json index 4cf95bc..81e2912 100644 --- a/package-lock.json +++ b/package-lock.json @@ -22,7 +22,7 @@ }, "devDependencies": { "@semantic-release/github": "^11.0.3", - "@tailwindcss/postcss": "^4.1.8", + "@tailwindcss/postcss": "^4.1.10", "@types/node": "22.15.30", "@types/react": "^19.1.6", "@types/react-dom": "^19.1.6", @@ -2589,9 +2589,9 @@ } }, "node_modules/@tailwindcss/node": { - "version": "4.1.8", - "resolved": "https://registry.npmjs.org/@tailwindcss/node/-/node-4.1.8.tgz", - "integrity": "sha512-OWwBsbC9BFAJelmnNcrKuf+bka2ZxCE2A4Ft53Tkg4uoiE67r/PMEYwCsourC26E+kmxfwE0hVzMdxqeW+xu7Q==", + "version": "4.1.10", + "resolved": "https://registry.npmjs.org/@tailwindcss/node/-/node-4.1.10.tgz", + "integrity": "sha512-2ACf1znY5fpRBwRhMgj9ZXvb2XZW8qs+oTfotJ2C5xR0/WNL7UHZ7zXl6s+rUqedL1mNi+0O+WQr5awGowS3PQ==", "dev": true, "license": "MIT", "dependencies": { @@ -2601,13 +2601,13 @@ "lightningcss": "1.30.1", "magic-string": "^0.30.17", "source-map-js": "^1.2.1", - "tailwindcss": "4.1.8" + "tailwindcss": "4.1.10" } }, "node_modules/@tailwindcss/oxide": { - "version": "4.1.8", - "resolved": "https://registry.npmjs.org/@tailwindcss/oxide/-/oxide-4.1.8.tgz", - "integrity": "sha512-d7qvv9PsM5N3VNKhwVUhpK6r4h9wtLkJ6lz9ZY9aeZgrUWk1Z8VPyqyDT9MZlem7GTGseRQHkeB1j3tC7W1P+A==", + "version": "4.1.10", + "resolved": "https://registry.npmjs.org/@tailwindcss/oxide/-/oxide-4.1.10.tgz", + "integrity": "sha512-v0C43s7Pjw+B9w21htrQwuFObSkio2aV/qPx/mhrRldbqxbWJK6KizM+q7BF1/1CmuLqZqX3CeYF7s7P9fbA8Q==", "dev": true, "hasInstallScript": true, "license": "MIT", @@ -2619,24 +2619,24 @@ "node": ">= 10" }, "optionalDependencies": { - "@tailwindcss/oxide-android-arm64": "4.1.8", - "@tailwindcss/oxide-darwin-arm64": "4.1.8", - "@tailwindcss/oxide-darwin-x64": "4.1.8", - "@tailwindcss/oxide-freebsd-x64": "4.1.8", - "@tailwindcss/oxide-linux-arm-gnueabihf": "4.1.8", - "@tailwindcss/oxide-linux-arm64-gnu": "4.1.8", - "@tailwindcss/oxide-linux-arm64-musl": "4.1.8", - "@tailwindcss/oxide-linux-x64-gnu": "4.1.8", - "@tailwindcss/oxide-linux-x64-musl": "4.1.8", - "@tailwindcss/oxide-wasm32-wasi": "4.1.8", - "@tailwindcss/oxide-win32-arm64-msvc": "4.1.8", - "@tailwindcss/oxide-win32-x64-msvc": "4.1.8" + "@tailwindcss/oxide-android-arm64": "4.1.10", + "@tailwindcss/oxide-darwin-arm64": "4.1.10", + "@tailwindcss/oxide-darwin-x64": "4.1.10", + "@tailwindcss/oxide-freebsd-x64": "4.1.10", + "@tailwindcss/oxide-linux-arm-gnueabihf": "4.1.10", + "@tailwindcss/oxide-linux-arm64-gnu": "4.1.10", + "@tailwindcss/oxide-linux-arm64-musl": "4.1.10", + "@tailwindcss/oxide-linux-x64-gnu": "4.1.10", + "@tailwindcss/oxide-linux-x64-musl": "4.1.10", + "@tailwindcss/oxide-wasm32-wasi": "4.1.10", + "@tailwindcss/oxide-win32-arm64-msvc": "4.1.10", + "@tailwindcss/oxide-win32-x64-msvc": "4.1.10" } }, "node_modules/@tailwindcss/oxide-android-arm64": { - "version": "4.1.8", - "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-android-arm64/-/oxide-android-arm64-4.1.8.tgz", - "integrity": "sha512-Fbz7qni62uKYceWYvUjRqhGfZKwhZDQhlrJKGtnZfuNtHFqa8wmr+Wn74CTWERiW2hn3mN5gTpOoxWKk0jRxjg==", + "version": "4.1.10", + "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-android-arm64/-/oxide-android-arm64-4.1.10.tgz", + "integrity": "sha512-VGLazCoRQ7rtsCzThaI1UyDu/XRYVyH4/EWiaSX6tFglE+xZB5cvtC5Omt0OQ+FfiIVP98su16jDVHDEIuH4iQ==", "cpu": [ "arm64" ], @@ -2651,9 +2651,9 @@ } }, "node_modules/@tailwindcss/oxide-darwin-arm64": { - "version": "4.1.8", - "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-darwin-arm64/-/oxide-darwin-arm64-4.1.8.tgz", - "integrity": "sha512-RdRvedGsT0vwVVDztvyXhKpsU2ark/BjgG0huo4+2BluxdXo8NDgzl77qh0T1nUxmM11eXwR8jA39ibvSTbi7A==", + "version": "4.1.10", + "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-darwin-arm64/-/oxide-darwin-arm64-4.1.10.tgz", + "integrity": "sha512-ZIFqvR1irX2yNjWJzKCqTCcHZbgkSkSkZKbRM3BPzhDL/18idA8uWCoopYA2CSDdSGFlDAxYdU2yBHwAwx8euQ==", "cpu": [ "arm64" ], @@ -2668,9 +2668,9 @@ } }, "node_modules/@tailwindcss/oxide-darwin-x64": { - "version": "4.1.8", - "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-darwin-x64/-/oxide-darwin-x64-4.1.8.tgz", - "integrity": "sha512-t6PgxjEMLp5Ovf7uMb2OFmb3kqzVTPPakWpBIFzppk4JE4ix0yEtbtSjPbU8+PZETpaYMtXvss2Sdkx8Vs4XRw==", + "version": "4.1.10", + "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-darwin-x64/-/oxide-darwin-x64-4.1.10.tgz", + "integrity": "sha512-eCA4zbIhWUFDXoamNztmS0MjXHSEJYlvATzWnRiTqJkcUteSjO94PoRHJy1Xbwp9bptjeIxxBHh+zBWFhttbrQ==", "cpu": [ "x64" ], @@ -2685,9 +2685,9 @@ } }, "node_modules/@tailwindcss/oxide-freebsd-x64": { - "version": "4.1.8", - "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-freebsd-x64/-/oxide-freebsd-x64-4.1.8.tgz", - "integrity": "sha512-g8C8eGEyhHTqwPStSwZNSrOlyx0bhK/V/+zX0Y+n7DoRUzyS8eMbVshVOLJTDDC+Qn9IJnilYbIKzpB9n4aBsg==", + "version": "4.1.10", + "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-freebsd-x64/-/oxide-freebsd-x64-4.1.10.tgz", + "integrity": "sha512-8/392Xu12R0cc93DpiJvNpJ4wYVSiciUlkiOHOSOQNH3adq9Gi/dtySK7dVQjXIOzlpSHjeCL89RUUI8/GTI6g==", "cpu": [ "x64" ], @@ -2702,9 +2702,9 @@ } }, "node_modules/@tailwindcss/oxide-linux-arm-gnueabihf": { - "version": "4.1.8", - "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-linux-arm-gnueabihf/-/oxide-linux-arm-gnueabihf-4.1.8.tgz", - "integrity": "sha512-Jmzr3FA4S2tHhaC6yCjac3rGf7hG9R6Gf2z9i9JFcuyy0u79HfQsh/thifbYTF2ic82KJovKKkIB6Z9TdNhCXQ==", + "version": "4.1.10", + "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-linux-arm-gnueabihf/-/oxide-linux-arm-gnueabihf-4.1.10.tgz", + "integrity": "sha512-t9rhmLT6EqeuPT+MXhWhlRYIMSfh5LZ6kBrC4FS6/+M1yXwfCtp24UumgCWOAJVyjQwG+lYva6wWZxrfvB+NhQ==", "cpu": [ "arm" ], @@ -2719,9 +2719,9 @@ } }, "node_modules/@tailwindcss/oxide-linux-arm64-gnu": { - "version": "4.1.8", - "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-linux-arm64-gnu/-/oxide-linux-arm64-gnu-4.1.8.tgz", - "integrity": "sha512-qq7jXtO1+UEtCmCeBBIRDrPFIVI4ilEQ97qgBGdwXAARrUqSn/L9fUrkb1XP/mvVtoVeR2bt/0L77xx53bPZ/Q==", + "version": "4.1.10", + "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-linux-arm64-gnu/-/oxide-linux-arm64-gnu-4.1.10.tgz", + "integrity": "sha512-3oWrlNlxLRxXejQ8zImzrVLuZ/9Z2SeKoLhtCu0hpo38hTO2iL86eFOu4sVR8cZc6n3z7eRXXqtHJECa6mFOvA==", "cpu": [ "arm64" ], @@ -2736,9 +2736,9 @@ } }, "node_modules/@tailwindcss/oxide-linux-arm64-musl": { - "version": "4.1.8", - "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-linux-arm64-musl/-/oxide-linux-arm64-musl-4.1.8.tgz", - "integrity": "sha512-O6b8QesPbJCRshsNApsOIpzKt3ztG35gfX9tEf4arD7mwNinsoCKxkj8TgEE0YRjmjtO3r9FlJnT/ENd9EVefQ==", + "version": "4.1.10", + "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-linux-arm64-musl/-/oxide-linux-arm64-musl-4.1.10.tgz", + "integrity": "sha512-saScU0cmWvg/Ez4gUmQWr9pvY9Kssxt+Xenfx1LG7LmqjcrvBnw4r9VjkFcqmbBb7GCBwYNcZi9X3/oMda9sqQ==", "cpu": [ "arm64" ], @@ -2753,9 +2753,9 @@ } }, "node_modules/@tailwindcss/oxide-linux-x64-gnu": { - "version": "4.1.8", - "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-linux-x64-gnu/-/oxide-linux-x64-gnu-4.1.8.tgz", - "integrity": "sha512-32iEXX/pXwikshNOGnERAFwFSfiltmijMIAbUhnNyjFr3tmWmMJWQKU2vNcFX0DACSXJ3ZWcSkzNbaKTdngH6g==", + "version": "4.1.10", + "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-linux-x64-gnu/-/oxide-linux-x64-gnu-4.1.10.tgz", + "integrity": "sha512-/G3ao/ybV9YEEgAXeEg28dyH6gs1QG8tvdN9c2MNZdUXYBaIY/Gx0N6RlJzfLy/7Nkdok4kaxKPHKJUlAaoTdA==", "cpu": [ "x64" ], @@ -2770,9 +2770,9 @@ } }, "node_modules/@tailwindcss/oxide-linux-x64-musl": { - "version": "4.1.8", - "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-linux-x64-musl/-/oxide-linux-x64-musl-4.1.8.tgz", - "integrity": "sha512-s+VSSD+TfZeMEsCaFaHTaY5YNj3Dri8rST09gMvYQKwPphacRG7wbuQ5ZJMIJXN/puxPcg/nU+ucvWguPpvBDg==", + "version": "4.1.10", + "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-linux-x64-musl/-/oxide-linux-x64-musl-4.1.10.tgz", + "integrity": "sha512-LNr7X8fTiKGRtQGOerSayc2pWJp/9ptRYAa4G+U+cjw9kJZvkopav1AQc5HHD+U364f71tZv6XamaHKgrIoVzA==", "cpu": [ "x64" ], @@ -2787,9 +2787,9 @@ } }, "node_modules/@tailwindcss/oxide-wasm32-wasi": { - "version": "4.1.8", - "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-wasm32-wasi/-/oxide-wasm32-wasi-4.1.8.tgz", - "integrity": "sha512-CXBPVFkpDjM67sS1psWohZ6g/2/cd+cq56vPxK4JeawelxwK4YECgl9Y9TjkE2qfF+9/s1tHHJqrC4SS6cVvSg==", + "version": "4.1.10", + "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-wasm32-wasi/-/oxide-wasm32-wasi-4.1.10.tgz", + "integrity": "sha512-d6ekQpopFQJAcIK2i7ZzWOYGZ+A6NzzvQ3ozBvWFdeyqfOZdYHU66g5yr+/HC4ipP1ZgWsqa80+ISNILk+ae/Q==", "bundleDependencies": [ "@napi-rs/wasm-runtime", "@emnapi/core", @@ -2816,10 +2816,70 @@ "node": ">=14.0.0" } }, + "node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@emnapi/core": { + "version": "1.4.3", + "dev": true, + "inBundle": true, + "license": "MIT", + "optional": true, + "dependencies": { + "@emnapi/wasi-threads": "1.0.2", + "tslib": "^2.4.0" + } + }, + "node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@emnapi/runtime": { + "version": "1.4.3", + "dev": true, + "inBundle": true, + "license": "MIT", + "optional": true, + "dependencies": { + "tslib": "^2.4.0" + } + }, + "node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@emnapi/wasi-threads": { + "version": "1.0.2", + "dev": true, + "inBundle": true, + "license": "MIT", + "optional": true, + "dependencies": { + "tslib": "^2.4.0" + } + }, + "node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@napi-rs/wasm-runtime": { + "version": "0.2.10", + "dev": true, + "inBundle": true, + "license": "MIT", + "optional": true, + "dependencies": { + "@emnapi/core": "^1.4.3", + "@emnapi/runtime": "^1.4.3", + "@tybys/wasm-util": "^0.9.0" + } + }, + "node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@tybys/wasm-util": { + "version": "0.9.0", + "dev": true, + "inBundle": true, + "license": "MIT", + "optional": true, + "dependencies": { + "tslib": "^2.4.0" + } + }, + "node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/tslib": { + "version": "2.8.0", + "dev": true, + "inBundle": true, + "license": "0BSD", + "optional": true + }, "node_modules/@tailwindcss/oxide-win32-arm64-msvc": { - "version": "4.1.8", - "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-win32-arm64-msvc/-/oxide-win32-arm64-msvc-4.1.8.tgz", - "integrity": "sha512-7GmYk1n28teDHUjPlIx4Z6Z4hHEgvP5ZW2QS9ygnDAdI/myh3HTHjDqtSqgu1BpRoI4OiLx+fThAyA1JePoENA==", + "version": "4.1.10", + "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-win32-arm64-msvc/-/oxide-win32-arm64-msvc-4.1.10.tgz", + "integrity": "sha512-i1Iwg9gRbwNVOCYmnigWCCgow8nDWSFmeTUU5nbNx3rqbe4p0kRbEqLwLJbYZKmSSp23g4N6rCDmm7OuPBXhDA==", "cpu": [ "arm64" ], @@ -2834,9 +2894,9 @@ } }, "node_modules/@tailwindcss/oxide-win32-x64-msvc": { - "version": "4.1.8", - "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-win32-x64-msvc/-/oxide-win32-x64-msvc-4.1.8.tgz", - "integrity": "sha512-fou+U20j+Jl0EHwK92spoWISON2OBnCazIc038Xj2TdweYV33ZRkS9nwqiUi2d/Wba5xg5UoHfvynnb/UB49cQ==", + "version": "4.1.10", + "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-win32-x64-msvc/-/oxide-win32-x64-msvc-4.1.10.tgz", + "integrity": "sha512-sGiJTjcBSfGq2DVRtaSljq5ZgZS2SDHSIfhOylkBvHVjwOsodBhnb3HdmiKkVuUGKD0I7G63abMOVaskj1KpOA==", "cpu": [ "x64" ], @@ -2851,17 +2911,17 @@ } }, "node_modules/@tailwindcss/postcss": { - "version": "4.1.8", - "resolved": "https://registry.npmjs.org/@tailwindcss/postcss/-/postcss-4.1.8.tgz", - "integrity": "sha512-vB/vlf7rIky+w94aWMw34bWW1ka6g6C3xIOdICKX2GC0VcLtL6fhlLiafF0DVIwa9V6EHz8kbWMkS2s2QvvNlw==", + "version": "4.1.10", + "resolved": "https://registry.npmjs.org/@tailwindcss/postcss/-/postcss-4.1.10.tgz", + "integrity": "sha512-B+7r7ABZbkXJwpvt2VMnS6ujcDoR2OOcFaqrLIo1xbcdxje4Vf+VgJdBzNNbrAjBj/rLZ66/tlQ1knIGNLKOBQ==", "dev": true, "license": "MIT", "dependencies": { "@alloc/quick-lru": "^5.2.0", - "@tailwindcss/node": "4.1.8", - "@tailwindcss/oxide": "4.1.8", + "@tailwindcss/node": "4.1.10", + "@tailwindcss/oxide": "4.1.10", "postcss": "^8.4.41", - "tailwindcss": "4.1.8" + "tailwindcss": "4.1.10" } }, "node_modules/@types/debug": { @@ -13025,9 +13085,9 @@ } }, "node_modules/tailwindcss": { - "version": "4.1.8", - "resolved": "https://registry.npmjs.org/tailwindcss/-/tailwindcss-4.1.8.tgz", - "integrity": "sha512-kjeW8gjdxasbmFKpVGrGd5T4i40mV5J2Rasw48QARfYeQ8YS9x02ON9SFWax3Qf616rt4Cp3nVNIj6Hd1mP3og==", + "version": "4.1.10", + "resolved": "https://registry.npmjs.org/tailwindcss/-/tailwindcss-4.1.10.tgz", + "integrity": "sha512-P3nr6WkvKV/ONsTzj6Gb57sWPMX29EPNPopo7+FcpkQaNsrNpZ1pv8QmrYI2RqEKD7mlGqLnGovlcYnBK0IqUA==", "devOptional": true, "license": "MIT" }, diff --git a/package.json b/package.json index 354b893..000ec8f 100644 --- a/package.json +++ b/package.json @@ -27,7 +27,7 @@ }, "devDependencies": { "@semantic-release/github": "^11.0.3", - "@tailwindcss/postcss": "^4.1.8", + "@tailwindcss/postcss": "^4.1.10", "@types/node": "22.15.30", "@types/react": "^19.1.6", "@types/react-dom": "^19.1.6", From 984134a52b86095da120d47da0921c6bedbf93c6 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Mon, 16 Jun 2025 16:40:57 +0000 Subject: [PATCH 04/17] build(deps-dev): bump tailwindcss from 4.1.8 to 4.1.10 Bumps [tailwindcss](https://github.com/tailwindlabs/tailwindcss/tree/HEAD/packages/tailwindcss) from 4.1.8 to 4.1.10. - [Release notes](https://github.com/tailwindlabs/tailwindcss/releases) - [Changelog](https://github.com/tailwindlabs/tailwindcss/blob/main/CHANGELOG.md) - [Commits](https://github.com/tailwindlabs/tailwindcss/commits/v4.1.10/packages/tailwindcss) --- updated-dependencies: - dependency-name: tailwindcss dependency-version: 4.1.10 dependency-type: direct:development update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] --- package-lock.json | 82 ++++++++++++++++++++++++++++++++++++++++++++--- package.json | 2 +- 2 files changed, 79 insertions(+), 5 deletions(-) diff --git a/package-lock.json b/package-lock.json index 4cf95bc..cf21c4a 100644 --- a/package-lock.json +++ b/package-lock.json @@ -30,7 +30,7 @@ "markdownlint-cli": "^0.45.0", "markdownlint-cli2": "^0.18.1", "postcss": "^8.5.4", - "tailwindcss": "^4.1.8", + "tailwindcss": "^4.1.10", "typescript": "5.8.3" } }, @@ -2604,6 +2604,13 @@ "tailwindcss": "4.1.8" } }, + "node_modules/@tailwindcss/node/node_modules/tailwindcss": { + "version": "4.1.8", + "resolved": "https://registry.npmjs.org/tailwindcss/-/tailwindcss-4.1.8.tgz", + "integrity": "sha512-kjeW8gjdxasbmFKpVGrGd5T4i40mV5J2Rasw48QARfYeQ8YS9x02ON9SFWax3Qf616rt4Cp3nVNIj6Hd1mP3og==", + "dev": true, + "license": "MIT" + }, "node_modules/@tailwindcss/oxide": { "version": "4.1.8", "resolved": "https://registry.npmjs.org/@tailwindcss/oxide/-/oxide-4.1.8.tgz", @@ -2816,6 +2823,66 @@ "node": ">=14.0.0" } }, + "node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@emnapi/core": { + "version": "1.4.3", + "dev": true, + "inBundle": true, + "license": "MIT", + "optional": true, + "dependencies": { + "@emnapi/wasi-threads": "1.0.2", + "tslib": "^2.4.0" + } + }, + "node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@emnapi/runtime": { + "version": "1.4.3", + "dev": true, + "inBundle": true, + "license": "MIT", + "optional": true, + "dependencies": { + "tslib": "^2.4.0" + } + }, + "node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@emnapi/wasi-threads": { + "version": "1.0.2", + "dev": true, + "inBundle": true, + "license": "MIT", + "optional": true, + "dependencies": { + "tslib": "^2.4.0" + } + }, + "node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@napi-rs/wasm-runtime": { + "version": "0.2.10", + "dev": true, + "inBundle": true, + "license": "MIT", + "optional": true, + "dependencies": { + "@emnapi/core": "^1.4.3", + "@emnapi/runtime": "^1.4.3", + "@tybys/wasm-util": "^0.9.0" + } + }, + "node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@tybys/wasm-util": { + "version": "0.9.0", + "dev": true, + "inBundle": true, + "license": "MIT", + "optional": true, + "dependencies": { + "tslib": "^2.4.0" + } + }, + "node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/tslib": { + "version": "2.8.0", + "dev": true, + "inBundle": true, + "license": "0BSD", + "optional": true + }, "node_modules/@tailwindcss/oxide-win32-arm64-msvc": { "version": "4.1.8", "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-win32-arm64-msvc/-/oxide-win32-arm64-msvc-4.1.8.tgz", @@ -2864,6 +2931,13 @@ "tailwindcss": "4.1.8" } }, + "node_modules/@tailwindcss/postcss/node_modules/tailwindcss": { + "version": "4.1.8", + "resolved": "https://registry.npmjs.org/tailwindcss/-/tailwindcss-4.1.8.tgz", + "integrity": "sha512-kjeW8gjdxasbmFKpVGrGd5T4i40mV5J2Rasw48QARfYeQ8YS9x02ON9SFWax3Qf616rt4Cp3nVNIj6Hd1mP3og==", + "dev": true, + "license": "MIT" + }, "node_modules/@types/debug": { "version": "4.1.12", "resolved": "https://registry.npmjs.org/@types/debug/-/debug-4.1.12.tgz", @@ -13025,9 +13099,9 @@ } }, "node_modules/tailwindcss": { - "version": "4.1.8", - "resolved": "https://registry.npmjs.org/tailwindcss/-/tailwindcss-4.1.8.tgz", - "integrity": "sha512-kjeW8gjdxasbmFKpVGrGd5T4i40mV5J2Rasw48QARfYeQ8YS9x02ON9SFWax3Qf616rt4Cp3nVNIj6Hd1mP3og==", + "version": "4.1.10", + "resolved": "https://registry.npmjs.org/tailwindcss/-/tailwindcss-4.1.10.tgz", + "integrity": "sha512-P3nr6WkvKV/ONsTzj6Gb57sWPMX29EPNPopo7+FcpkQaNsrNpZ1pv8QmrYI2RqEKD7mlGqLnGovlcYnBK0IqUA==", "devOptional": true, "license": "MIT" }, diff --git a/package.json b/package.json index 354b893..3c61a53 100644 --- a/package.json +++ b/package.json @@ -35,7 +35,7 @@ "markdownlint-cli": "^0.45.0", "markdownlint-cli2": "^0.18.1", "postcss": "^8.5.4", - "tailwindcss": "^4.1.8", + "tailwindcss": "^4.1.10", "typescript": "5.8.3" } } From c7fadd0f8271b88650dd388e2306896932472e5c Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Wed, 18 Jun 2025 07:56:07 +0000 Subject: [PATCH 05/17] build(deps-dev): bump postcss from 8.5.4 to 8.5.6 Bumps [postcss](https://github.com/postcss/postcss) from 8.5.4 to 8.5.6. - [Release notes](https://github.com/postcss/postcss/releases) - [Changelog](https://github.com/postcss/postcss/blob/main/CHANGELOG.md) - [Commits](https://github.com/postcss/postcss/compare/8.5.4...8.5.6) --- updated-dependencies: - dependency-name: postcss dependency-version: 8.5.6 dependency-type: direct:development update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] --- package-lock.json | 70 +++-------------------------------------------- package.json | 2 +- 2 files changed, 5 insertions(+), 67 deletions(-) diff --git a/package-lock.json b/package-lock.json index e7ee2c2..a504141 100644 --- a/package-lock.json +++ b/package-lock.json @@ -29,7 +29,7 @@ "autoprefixer": "^10.4.21", "markdownlint-cli": "^0.45.0", "markdownlint-cli2": "^0.18.1", - "postcss": "^8.5.4", + "postcss": "^8.5.6", "tailwindcss": "^4.1.10", "typescript": "5.8.3" } @@ -2604,13 +2604,6 @@ "tailwindcss": "4.1.10" } }, - "node_modules/@tailwindcss/node/node_modules/tailwindcss": { - "version": "4.1.8", - "resolved": "https://registry.npmjs.org/tailwindcss/-/tailwindcss-4.1.8.tgz", - "integrity": "sha512-kjeW8gjdxasbmFKpVGrGd5T4i40mV5J2Rasw48QARfYeQ8YS9x02ON9SFWax3Qf616rt4Cp3nVNIj6Hd1mP3og==", - "dev": true, - "license": "MIT" - }, "node_modules/@tailwindcss/oxide": { "version": "4.1.10", "resolved": "https://registry.npmjs.org/@tailwindcss/oxide/-/oxide-4.1.10.tgz", @@ -2931,13 +2924,6 @@ "tailwindcss": "4.1.10" } }, - "node_modules/@tailwindcss/postcss/node_modules/tailwindcss": { - "version": "4.1.8", - "resolved": "https://registry.npmjs.org/tailwindcss/-/tailwindcss-4.1.8.tgz", - "integrity": "sha512-kjeW8gjdxasbmFKpVGrGd5T4i40mV5J2Rasw48QARfYeQ8YS9x02ON9SFWax3Qf616rt4Cp3nVNIj6Hd1mP3og==", - "dev": true, - "license": "MIT" - }, "node_modules/@types/debug": { "version": "4.1.12", "resolved": "https://registry.npmjs.org/@types/debug/-/debug-4.1.12.tgz", @@ -5166,54 +5152,6 @@ } } }, - "node_modules/fumadocs-ui/node_modules/fumadocs-core": { - "version": "15.5.1", - "resolved": "https://registry.npmjs.org/fumadocs-core/-/fumadocs-core-15.5.1.tgz", - "integrity": "sha512-5eJPJw+BFWFdgrtWPQ9aAZAhhsyuZAwth8OjBd9R77sXoIoae4Y4lJZMq3BeSpJZcuIAOVbSCS+pJhsBAoXJ8g==", - "license": "MIT", - "dependencies": { - "@formatjs/intl-localematcher": "^0.6.1", - "@orama/orama": "^3.1.6", - "@shikijs/rehype": "^3.4.2", - "@shikijs/transformers": "^3.4.2", - "github-slugger": "^2.0.0", - "hast-util-to-estree": "^3.1.3", - "hast-util-to-jsx-runtime": "^2.3.6", - "image-size": "^2.0.2", - "negotiator": "^1.0.0", - "react-remove-scroll": "^2.6.3", - "remark": "^15.0.0", - "remark-gfm": "^4.0.1", - "remark-rehype": "^11.1.2", - "scroll-into-view-if-needed": "^3.1.0", - "shiki": "^3.4.2", - "unist-util-visit": "^5.0.0" - }, - "peerDependencies": { - "@oramacloud/client": "1.x.x || 2.x.x", - "algoliasearch": "5.x.x", - "next": "14.x.x || 15.x.x", - "react": "18.x.x || 19.x.x", - "react-dom": "18.x.x || 19.x.x" - }, - "peerDependenciesMeta": { - "@oramacloud/client": { - "optional": true - }, - "algoliasearch": { - "optional": true - }, - "next": { - "optional": true - }, - "react": { - "optional": true - }, - "react-dom": { - "optional": true - } - } - }, "node_modules/function-bind": { "version": "1.1.2", "resolved": "https://registry.npmjs.org/function-bind/-/function-bind-1.1.2.tgz", @@ -11511,9 +11449,9 @@ } }, "node_modules/postcss": { - "version": "8.5.4", - "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.4.tgz", - "integrity": "sha512-QSa9EBe+uwlGTFmHsPKokv3B/oEMQZxfqW0QqNCyhpa6mB1afzulwn8hihglqAb2pOw+BJgNlmXQ8la2VeHB7w==", + "version": "8.5.6", + "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.6.tgz", + "integrity": "sha512-3Ybi1tAuwAP9s0r1UQ2J4n5Y0G05bJkpUIO0/bI9MhwmD70S5aTWbXGBwxHrelT+XM1k6dM0pk+SwNkpTRN7Pg==", "dev": true, "funding": [ { diff --git a/package.json b/package.json index d2e9753..30a1341 100644 --- a/package.json +++ b/package.json @@ -34,7 +34,7 @@ "autoprefixer": "^10.4.21", "markdownlint-cli": "^0.45.0", "markdownlint-cli2": "^0.18.1", - "postcss": "^8.5.4", + "postcss": "^8.5.6", "tailwindcss": "^4.1.10", "typescript": "5.8.3" } From e548e6804bdae685fe7b6b5b993ae980562fb900 Mon Sep 17 00:00:00 2001 From: JasonKrik Date: Wed, 18 Jun 2025 15:59:00 +0200 Subject: [PATCH 06/17] refactor: remove CustomNavbar and update navigation configuration --- app/docs/[[...slug]]/page.tsx | 2 - app/docs/layout.tsx | 2 +- app/layout.config.tsx | 4 +- lib/._components | Bin 4096 -> 0 bytes lib/components/CustomNavbar.tsx | 84 -------------------------------- next.config.mjs | 4 +- package.json | 5 +- 7 files changed, 7 insertions(+), 94 deletions(-) delete mode 100644 lib/._components delete mode 100644 lib/components/CustomNavbar.tsx diff --git a/app/docs/[[...slug]]/page.tsx b/app/docs/[[...slug]]/page.tsx index e59fd03..72a97c0 100644 --- a/app/docs/[[...slug]]/page.tsx +++ b/app/docs/[[...slug]]/page.tsx @@ -3,7 +3,6 @@ import { DocsPage, DocsBody } from 'fumadocs-ui/page'; import { notFound } from 'next/navigation'; import { source } from '@/lib/source'; import { generatePageMetadata, getCanonicalUrl } from '@/lib/seo-utils'; -import { CustomNavbar } from '@/lib/components/CustomNavbar'; import { getFinalPageTitle } from '@/lib/h1-extractor'; import { readFile } from 'fs/promises'; import { getMDXComponents } from '@/mdx-components'; @@ -24,7 +23,6 @@ export default async function Page({ return ( - diff --git a/app/docs/layout.tsx b/app/docs/layout.tsx index 818838e..c589dd9 100644 --- a/app/docs/layout.tsx +++ b/app/docs/layout.tsx @@ -10,7 +10,7 @@ export default function Layout({ children }: { children: ReactNode }) { tree={source.pageTree} nav={{ title: 'DeployStack Docs', - url: '/docs', + url: '/', }} sidebar={{ defaultOpenLevel: 1 diff --git a/app/layout.config.tsx b/app/layout.config.tsx index 150504f..6a092c4 100644 --- a/app/layout.config.tsx +++ b/app/layout.config.tsx @@ -1,10 +1,10 @@ import type { BaseLayoutProps } from 'fumadocs-ui/layouts/shared'; export const baseOptions: BaseLayoutProps = { - // Navigation bar configuration (now handled by CustomNavbar) + // Navigation bar configuration nav: { title: 'DeployStack Docs', - url: '/docs', + url: '/', }, // GitHub repository for edit links diff --git a/lib/._components b/lib/._components deleted file mode 100644 index 97b64adda1edb2ffc55b4e3dc9b83217f0c88bc5..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 4096 zcmZQz6=P>$Vqox1Ojhs@R)|o50+1L3ClDJkFz{^v(m+1nBL)UWIUt(=a103vf+zv$ zV3+~K+-O=D5#plB`MG+D1qC^&dId%KWvO|IdC92^j7$twk9=neOSU$mX&vQ`hQMeD zjE2By2#kinXb6mkz-S1JhQMeDjE2By2#kgR_7DJdHbEE+ -
- {/* Logo and Main Navigation */} -
-
- - DeployStack - DeployStack Logo - -
- - {/* Desktop Navigation */} -
- -
-
- - {/* Right Side Actions */} -
- {/* Mobile Menu Button */} -
- -
- - {/* GitHub Link */} - - - GitHub - - - {/* Login Button */} - - Login - -
-
- - ); -} diff --git a/next.config.mjs b/next.config.mjs index 336687c..107a230 100644 --- a/next.config.mjs +++ b/next.config.mjs @@ -7,8 +7,8 @@ const config = { reactStrictMode: true, output: 'export', // Enable static HTML export trailingSlash: true, // Required for static export - basePath: '/docs', // Set base path for the application - assetPrefix: '/docs', // Ensure assets are also prefixed with /docs + // basePath: '/docs', // Set base path for the application + // assetPrefix: '/docs', // Ensure assets are also prefixed with /docs images: { unoptimized: true // Required for static export }, diff --git a/package.json b/package.json index 30a1341..2ff4f0d 100644 --- a/package.json +++ b/package.json @@ -5,9 +5,8 @@ "private": true, "scripts": { "dev": "next dev", - "build": "next build && npm run move-assets", - "move-assets": "mkdir -p out/docs/_next && cp -r out/_next/* out/docs/_next/ && rm -rf out/_next", - "start": "next start", + "build": "next build", + "start": "npx serve@latest out", "lint:md": "npx markdownlint-cli2 '**/*.md' '#node_modules' '#.github'", "lint:links": "node check-links.js", "semantic-release": "semantic-release", From 32b5ec630623a07d9c65da2d61635a68412c8c34 Mon Sep 17 00:00:00 2001 From: JasonKrik Date: Wed, 18 Jun 2025 16:48:18 +0200 Subject: [PATCH 07/17] Add comprehensive documentation for multi-service support and parser implementations - Introduced new documentation for multi-service support in docker-to-iac, detailing how multiple services are handled in Docker configurations. - Added parser explanation documentation, outlining how Docker run commands and Docker Compose files are translated into various IaC templates. - Created detailed documentation for AWS CloudFormation, DigitalOcean, Render.com, and Helm parsers, including prerequisites, architecture, supported variables, and multi-service capabilities. - Updated project structure documentation to reflect the organization of source code, tests, and configuration files. - Added a quickstart guide for using the docker-to-iac module, including installation and usage examples. - Enhanced the main DeployStack documentation to provide an overview of the ecosystem and supported cloud providers. --- app/{docs => }/[[...slug]]/page.tsx | 24 +- app/docs/layout.tsx | 22 - app/docs/sitemap.xml/route.ts | 30 - .../application-logo-configuration.mdx | 60 ++ .../deploystack/deploystack-config-file.mdx | 259 ++++++ .../deploystack-configuration-directory.mdx | 71 ++ .../docker-compose-requirements.mdx | 102 +++ .../docs/deploystack/getting-started.mdx | 194 +++++ .../docs/deploystack/github-application.mdx | 69 ++ .../docs/deploystack/iac-lifecycle.mdx | 88 ++ .../docs/deploystack/index.mdx | 23 + .../docs/deploystack/multiple-branches.mdx | 150 ++++ .../docs/deploystack/one-click-deploy.mdx | 157 ++++ .../docs/deploystack/troubleshooting.mdx | 151 ++++ .../docs/docker-to-iac/api.mdx | 790 ++++++++++++++++++ .../docker-to-iac/example-of-a-new-parser.mdx | 383 +++++++++ .../docs/docker-to-iac/index.mdx | 50 ++ .../docs/docker-to-iac/limitations.mdx | 89 ++ .../docker-to-iac/multi-services-support.mdx | 78 ++ .../docs/docker-to-iac/parser-explanation.mdx | 61 ++ .../parser/aws-cloudformation.mdx | 97 +++ .../docker-to-iac/parser/digitalocean.mdx | 189 +++++ .../docs/docker-to-iac/parser/helm.mdx | 210 +++++ .../docs/docker-to-iac/parser/index.mdx | 14 + .../docs/docker-to-iac/parser/render.com.mdx | 133 +++ .../docs/docker-to-iac/project-structure.mdx | 175 ++++ .../docs/docker-to-iac/quickstart.mdx | 64 ++ .../docs/index.mdx | 83 ++ .../application-logo-configuration.mdx | 2 +- docs/deploystack/deploystack-config-file.mdx | 6 +- .../deploystack-configuration-directory.mdx | 12 +- .../docker-compose-requirements.mdx | 14 +- docs/deploystack/getting-started.mdx | 4 +- docs/deploystack/github-application.mdx | 10 +- docs/deploystack/iac-lifecycle.mdx | 6 +- docs/deploystack/index.mdx | 10 +- docs/deploystack/multiple-branches.mdx | 6 +- docs/deploystack/one-click-deploy.mdx | 4 +- docs/deploystack/troubleshooting.mdx | 10 +- docs/docker-to-iac/api.mdx | 2 +- .../docker-to-iac/example-of-a-new-parser.mdx | 2 +- docs/docker-to-iac/index.mdx | 4 +- docs/docker-to-iac/limitations.mdx | 2 +- docs/docker-to-iac/multi-services-support.mdx | 4 +- docs/docker-to-iac/parser-explanation.mdx | 6 +- .../parser/aws-cloudformation.mdx | 2 +- docs/docker-to-iac/parser/digitalocean.mdx | 2 +- docs/docker-to-iac/parser/helm.mdx | 2 +- docs/docker-to-iac/parser/index.mdx | 10 +- docs/docker-to-iac/parser/render.com.mdx | 4 +- docs/docker-to-iac/project-structure.mdx | 4 +- docs/docker-to-iac/quickstart.mdx | 2 +- docs/index.mdx | 18 +- lib/source.ts | 7 +- 54 files changed, 3836 insertions(+), 135 deletions(-) rename app/{docs => }/[[...slug]]/page.tsx (78%) delete mode 100644 app/docs/layout.tsx delete mode 100644 app/docs/sitemap.xml/route.ts create mode 100644 docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/application-logo-configuration.mdx create mode 100644 docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/deploystack-config-file.mdx create mode 100644 docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/deploystack-configuration-directory.mdx create mode 100644 docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/docker-compose-requirements.mdx create mode 100644 docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/getting-started.mdx create mode 100644 docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/github-application.mdx create mode 100644 docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/iac-lifecycle.mdx create mode 100644 docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/index.mdx create mode 100644 docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/multiple-branches.mdx create mode 100644 docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/one-click-deploy.mdx create mode 100644 docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/troubleshooting.mdx create mode 100644 docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/api.mdx create mode 100644 docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/example-of-a-new-parser.mdx create mode 100644 docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/index.mdx create mode 100644 docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/limitations.mdx create mode 100644 docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/multi-services-support.mdx create mode 100644 docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/parser-explanation.mdx create mode 100644 docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/parser/aws-cloudformation.mdx create mode 100644 docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/parser/digitalocean.mdx create mode 100644 docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/parser/helm.mdx create mode 100644 docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/parser/index.mdx create mode 100644 docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/parser/render.com.mdx create mode 100644 docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/project-structure.mdx create mode 100644 docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/quickstart.mdx create mode 100644 docs-backup-2025-06-18T14-33-44-828Z/docs/index.mdx diff --git a/app/docs/[[...slug]]/page.tsx b/app/[[...slug]]/page.tsx similarity index 78% rename from app/docs/[[...slug]]/page.tsx rename to app/[[...slug]]/page.tsx index 72a97c0..94cd965 100644 --- a/app/docs/[[...slug]]/page.tsx +++ b/app/[[...slug]]/page.tsx @@ -1,4 +1,5 @@ import type { Metadata } from 'next'; +import { DocsLayout } from 'fumadocs-ui/layouts/docs'; import { DocsPage, DocsBody } from 'fumadocs-ui/page'; import { notFound } from 'next/navigation'; import { source } from '@/lib/source'; @@ -6,6 +7,7 @@ import { generatePageMetadata, getCanonicalUrl } from '@/lib/seo-utils'; import { getFinalPageTitle } from '@/lib/h1-extractor'; import { readFile } from 'fs/promises'; import { getMDXComponents } from '@/mdx-components'; +import { baseOptions } from '../layout.config'; export default async function Page({ params, @@ -22,11 +24,23 @@ export default async function Page({ const MDX = page.data.body; return ( - - - - - + + + + + + + ); } diff --git a/app/docs/layout.tsx b/app/docs/layout.tsx deleted file mode 100644 index c589dd9..0000000 --- a/app/docs/layout.tsx +++ /dev/null @@ -1,22 +0,0 @@ -import { DocsLayout } from 'fumadocs-ui/layouts/docs'; -import type { ReactNode } from 'react'; -import { baseOptions } from '../layout.config'; -import { source } from '../../lib/source'; - -export default function Layout({ children }: { children: ReactNode }) { - return ( - - {children} - - ); -} diff --git a/app/docs/sitemap.xml/route.ts b/app/docs/sitemap.xml/route.ts deleted file mode 100644 index 25f1e6e..0000000 --- a/app/docs/sitemap.xml/route.ts +++ /dev/null @@ -1,30 +0,0 @@ -import { source } from '@/lib/source'; -import { getCanonicalUrl } from '@/lib/seo-utils'; - -export const dynamic = 'force-static'; -export const revalidate = false; - -export async function GET() { - const pages = source.getPages(); - - const sitemap = ` - -${pages - .map((page) => { - const url = getCanonicalUrl(page.url); - return ` - ${url} - ${new Date().toISOString()} - weekly - 0.8 - `; - }) - .join('\n')} -`; - - return new Response(sitemap, { - headers: { - 'Content-Type': 'application/xml', - }, - }); -} diff --git a/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/application-logo-configuration.mdx b/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/application-logo-configuration.mdx new file mode 100644 index 0000000..5535809 --- /dev/null +++ b/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/application-logo-configuration.mdx @@ -0,0 +1,60 @@ +--- +title: Application Logo Configuration +description: DeployStack logo configuration guide. Add a custom logo to your application with automatic WebP conversion, CDN delivery, and square format optimization. +--- + +# Application Logo Configuration + +Add a custom logo to make your application stand out in the DeployStack catalog. Your logo will be automatically optimized and served through our CDN for the best performance. + +## Adding Your Logo + +Configure your logo in `.deploystack/config.yml` - [DeployStack Configuration File Reference](/docs/deploystack/deploystack-config-file): + +```yaml +application: + logo: "https://example.com/path/to/logo.png" +``` + +## Logo Requirements + +### Supported Formats + +- PNG (`.png`) +- JPEG (`.jpg`, `.jpeg`) +- WebP (`.webp`) +- SVG (`.svg`) + +### Size Guidelines + +- Maximum input: 2 MB. +- Final output will be: + - Square format (1:1 aspect ratio) + - Maximum 500x500 pixels +- Input images will be: + - Resized if larger than 500px in either dimension + - Centered and cropped to maintain 1:1 aspect ratio + - Padded with transparency if needed to achieve square format + +## Image Processing + +When you configure a logo, DeployStack automatically: + +1. Downloads your original image +2. Optimizes it for web delivery +3. Converts it to WebP format +4. Stores it on our CDN +5. Serves it through our global CDN network + +### Optimization Process + +- Images larger than 500px in either dimension are resized +- Conversion to WebP for optimal compression +- Automatic quality optimization for web delivery + +## Notes + +- The logo configuration is optional +- You can update your logo at any time by modifying the config file +- Logo changes are processed only when made on the default branch +- Previous logo versions are automatically cleaned up diff --git a/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/deploystack-config-file.mdx b/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/deploystack-config-file.mdx new file mode 100644 index 0000000..78d2686 --- /dev/null +++ b/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/deploystack-config-file.mdx @@ -0,0 +1,259 @@ +--- +title: DeployStack Config File Reference +description: Documentation for DeployStack's config.yml schema. Customize your application's presentation with automatic IDE validation and flexible repository metadata overrides. +--- + +# DeployStack Configuration File Reference + +The `.deploystack/config.yml` file allows you to customize how your application appears in the DeployStack catalog and deployment interfaces. This configuration file supports automatic validation in popular IDEs through SchemaStore integration. + +## Configuration File Location + +Create a `config.yml` file in your repository's `.deploystack` directory: + +```bash +your-repository/ +├── .deploystack/ +│ ├── config.yml +│ └── docker-compose.yml (example, or docker-run.txt) +└── README.md +``` + +## Basic Configuration + +Here's a minimal configuration example: + +```yaml +application: + name: "My Application" + description: "A scalable web application with Redis caching" + logo: "https://example.com/path/to/logo.png" +``` + +## Configuration Options + +### Application Settings + +When you submit a repository to DeployStack, we automatically use: + +- Repository name as the application name +- Repository description as the application description + +You can override these values using the `config.yml` (only on your main branch) file: + +| Property | Type | Description | Constraints | +|----------|------|-------------|-------------| +| `mappings` | Array | Defines relationships between services for connection configuration | Required | +| `mappings[].fromService` | String | Service that needs to connect to another service | Required | +| `mappings[].toService` | String | Service being connected to | Required | +| `mappings[].environmentVariables` | Array of Strings | Environment variable names that reference the target service | Required | +| `mappings[].property` | String | Type of connection property to reference (e.g., 'connectionString', 'hostport') | Optional, defaults to 'hostport' | + +The override process follows this order: + +1. DeployStack first uses your repository name and description +2. If present, values in `.deploystack/config.yml` override the repository metadata + +### Branch Deployment Settings + +Before configuring multiple branch deployments, ensure you have installed the [DeployStack Repository Sync GitHub App](/docs/deploystack/github-application), as it's required for branch monitoring and template updates. + +You can configure multiple branch deployments using the `deployment.branches` section: + +| Property | Type | Description | Constraints | +|----------|------|-------------|-------------| +| `label` | String | Display name for the branch | Maximum 20 characters | +| `description` | String | Explain the branch's purpose or version | Maximum 100 characters | +| `active` | Boolean | Whether this branch is available for deployment | Optional, defaults to true | +| `priority` | Number | Order in which branches appear (lower numbers first) | Minimum value: 1 | +| `exclude_providers` | Array | Optional list of cloud providers to exclude from template generation for this branch | Values must be valid provider codes: "aws", "rnd", "dop" | + +The default branch always has `priority: 0` and appears first in the deployment options, regardless of other branch priorities. + +Example configuration for multiple branches: + +```yaml +application: + name: "My Application" + description: "A scalable web application" + +deployment: + branches: + v2: + label: "Beta (v2.x)" + description: "Preview of upcoming v2.x release" + priority: 1 + exclude_providers: + - "aws" # Exclude AWS CloudFormation for this branch + v3: + label: "Alpha (v3.x)" + description: "Early preview of v3.x" + priority: 2 +``` + +Each branch configuration allows you to: + +- Provide a user-friendly label for the version +- Include a description explaining the branch's purpose +- Control deployment availability with the `active` flag +- Set display order using `priority` + +When multiple branches are configured: + +- DeployStack generates separate deployment templates for each branch +- Users can choose which version to deploy +- The GitHub App monitors all configured branches for updates +- The default branch is always listed first with implicit `priority: 0` + +This is especially useful for projects that maintain multiple active versions simultaneously, such as stable and beta releases. + +The optional `exclude_providers` array allows you to specify which cloud providers should be excluded from template generation for particular branches. This is useful when certain features in a branch version may not be compatible with specific cloud providers. Valid provider codes are: + +Please check our [current supported provider list here](/docs/docker-to-iac/parser/index). + +For example, if your beta version uses features only supported in DigitalOcean, you might exclude the other providers: + +```yaml +v2-beta: + label: "Beta" + description: "Beta version with DigitalOcean-specific features" + exclude_providers: + - "aws" + - "rnd" +``` + +If no providers are excluded, templates will be generated for all supported cloud providers. + +### Service Connections + +You can configure service-to-service communication for multi-container applications using the `serviceConnections` property within each branch configuration. This feature is particularly useful for applications where services need to communicate with each other (e.g., web apps connecting to databases). + +| Property | Type | Description | Constraints | +|----------|------|-------------|-------------| +| `mappings` | Array | Defines relationships between services for connection configuration | Required | +| `mappings[].fromService` | String | Service that needs to connect to another service | Required | +| `mappings[].toService` | String | Service being connected to | Required | +| `mappings[].environmentVariables` | Array of Strings | Environment variable names that reference the target service | Required | + +Example configuration for service connections: + +```yaml +deployment: + branches: + main: + label: "Production" + description: "Production release" + serviceConnections: + mappings: + - fromService: "app" + toService: "db" + environmentVariables: + - "DATABASE_HOST" + - "DATABASE_URL" + property: "connectionString" + - fromService: "frontend" + toService: "api" + environmentVariables: + - "API_URL" + property: "hostport" +``` + +This configuration tells DeployStack how to properly configure communication between: + +- The "app" service and the "db" service through the DATABASE_HOST and DATABASE_URL environment variables +- The "frontend" service and the "api" service through the API_URL environment variable + +When templates are generated, DeployStack will transform these environment variables according to each cloud provider's specific service discovery mechanism: + +- For Render.com: Uses Blueprint's `fromService` syntax +- For DigitalOcean App Platform: Uses direct service name references + +For example, if your docker-compose.yml contains: + +```yaml +services: + app: + image: node:alpine + environment: + DATABASE_HOST: db + db: + image: mariadb:latest +``` + +The generated Render.com template would transform DATABASE_HOST to use their service discovery syntax: + +```yaml +services: + - name: app + # ...other configuration... + envVars: + - key: DATABASE_HOST + fromService: + name: db + type: pserv + property: hostport +``` + +## Schema Validation + +The configuration file is automatically validated against our JSON Schema when using supported IDEs (VS Code, IntelliJ, etc.). The schema is available at: + +```bash +https://cdnx.deploystack.io/schema/config.yml.json +``` + +## Notes + +- Changes to the configuration file are only processed when made on your repository's default branch +- The logo URL must be accessible and point to a valid image file +- All configuration properties are optional, but providing them improves your application's visibility in the DeployStack catalog + +## Usage Examples + +### Override Repository Metadata + +```yaml +application: + name: "Redis Cache Manager" # Overrides repository name + description: "A more detailed description that better explains your application" # Overrides repository description + logo: "https://example.com/logos/redis-manager.png" +``` + +### Configure Multiple Branch Deployments with Service Connections + +```yaml +deployment: + branches: + stable: + label: "Stable" + description: "Production-ready version" + priority: 1 + serviceConnections: + mappings: + - fromService: "web" + toService: "api" + environmentVariables: + - "API_ENDPOINT" + - fromService: "api" + toService: "db" + environmentVariables: + - "DB_HOST" + - "DB_CONNECTION" + + beta: + label: "Beta" + description: "Preview of upcoming features" + priority: 2 + exclude_providers: + - "aws" # Beta version not supported on AWS + serviceConnections: + mappings: + - fromService: "web" + toService: "api" + environmentVariables: + - "API_ENDPOINT" +``` + +### Minimal Configuration example for logo update + +Please visit our [Application Logo Configuration](/docs/deploystack/application-logo-configuration) page. diff --git a/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/deploystack-configuration-directory.mdx b/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/deploystack-configuration-directory.mdx new file mode 100644 index 0000000..fd13942 --- /dev/null +++ b/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/deploystack-configuration-directory.mdx @@ -0,0 +1,71 @@ +--- +title: .deploystack Directory Reference +description: Technical guide for setting up the .deploystack directory to manage Infrastructure as Code template generation and updates across your repository. +--- + +# .deploystack Directory Reference + +The `.deploystack` directory in your repository contains configuration files that DeployStack uses to generate and maintain your Infrastructure as Code templates. Creating this repo allows you to enable the [lifecycle of IaC](/docs/deploystack/iac-lifecycle). The deploystack configurations repo only makes sense if you also [install DeployStack GitHub app](/docs/deploystack/github-application). Otherwise, changes to DeployStack backend will not be recognized. + + +`.deploystack` directory is optional. You don't need to create it to submit your repository to deploystack.io. + + +## Directory Structure + +```bash +.deploystack/ +├── docker-compose.yml # Docker Compose configuration +├── docker-run.txt # Docker run command +├── env # Environment variables (optional) +``` + +## Configuration Files + +### DeployStack Configuration File + +Please read more at [DeployStack Configuration File Reference](/docs/deploystack/deploystack-config-file). + +### Docker Configuration + +Choose one of the following: + +- `docker-compose.yml` - Standard Docker Compose configuration +- `docker-run.txt` - Single Docker run command + +Example `docker-compose.yml`: + +```yaml +version: '3' +services: + web: + image: nginx:alpine + ports: + - "80:80" +``` + +Example `docker-run.txt`: + +```bash +docker run -d -p 80:80 nginx:alpine +``` + +### Environment Variables + +Please read more from our [environment variables](/docs/deploystack/docker-environment-variables) page. + +## Automatic Updates + +When the [DeployStack GitHub App](/docs/deploystack/github-application) is installed: + +1. Changes to specific (`docker-compose.yml` & `docker-run.txt`) file in `.deploystack/` trigger template updates +2. Updates only process when changes occur on the default branch +3. New templates are generated and stored in the [deploy-templates](https://github.com/deploystackio/deploy-templates) repository + +## Important Notes + +- The `.deploystack` directory is **optional** +- Without this directory, automatic template updates are **not** available +- You can add the directory and install the [DeployStack GitHub Sync App](/docs/deploystack/github-application) at any time +- [Environment variables](/docs/deploystack/docker-environment-variables) and [DeployStack config](/docs/deploystack/deploystack-config-file) are optional components +- Only one Docker configuration file should be used (either compose or run) diff --git a/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/docker-compose-requirements.mdx b/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/docker-compose-requirements.mdx new file mode 100644 index 0000000..a54cf11 --- /dev/null +++ b/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/docker-compose-requirements.mdx @@ -0,0 +1,102 @@ +--- +title: Docker Compose Requirements +description: Technical requirements for using Docker Compose with DeployStack's cloud deployment automation. Includes supported properties, registry options, and validation rules. +--- + +# Docker Compose Requirements + +DeployStack is designed to work with Docker Compose files that meet specific requirements. This page outlines what we support and what limitations you need to be aware of. + +## Core Requirements + +Your `docker-compose.yml` file must: + +1. Use pre-built Docker images +2. Reference public images from Docker Hub or another registries -> check [Supported Registries](/docs/docker-to-iac/supported-registries) +3. Be a valid Docker Compose file (version 3 and above) + +Your docker-compose file does not necessarily have to be called `docker-compose.yml` and does not have to be located in the root directory. You can rename your docker compose file and store it in any sub directory. + +If your docker compose file is not located in the root directory and has not `docker-compose.yml` as the filename, you must submit the full path name to us by using the submit form [deploystack.io/submit](https://deploystack.io/submit) i.e.: `https://github.com/vuejs/vitepress/tree/main/deployment/docker-compose.yaml`. + +## Image Requirements + +### Must Use Pre-built Images + +Your services must specify the `image` property. For example: + +```yaml title="docker-compose.yml" +# ✅ Supported +services: + app: + image: nginx:latest + ports: + - "80:80" +``` + +### Build Instructions Not Supported + +We do not support services that use the `build` directive: + +```yaml title="docker-compose.yml" +# ❌ Not Supported +services: + app: + build: + context: ./build/app + dockerfile: Dockerfile +``` + +## Why These Requirements? + +The infrastructure templates we generate require specific, immutable container images to ensure consistent deployments. Cloud providers need to know exactly which image to pull, which is why we require pre-built images. + +## Supported Docker Compose Properties + +We currently support these Docker Compose properties -> please check [Supported Docker Compose Variables](/docs/docker-to-iac/supported-docker-compose-variables). + +### Kubernetes/Helm + +When generating Helm charts for Kubernetes: + +- Database services (MySQL, PostgreSQL, Redis, etc.) are converted to Bitnami Helm chart dependencies +- Environment variables are split between ConfigMaps (regular variables) and Secrets (sensitive data) +- Each service in your Docker Compose becomes a separate Deployment and Service +- Volume mounts are supported and configured as needed + +This allows for better security practices and easier management of your application on Kubernetes. + +## Multiple Services Support + +DeployStack can handle Docker Compose files with multiple services, but support varies by cloud provider: + +- Some providers support deploying all services at once +- Others will only deploy the first service in your compose file +- Kubernetes (Helm) supports multi-service deployments with each service becoming a separate Deployment + +Check the specific [Multi Services Support](/docs/docker-to-iac/multi-services-support) for details about multi-service support. + +## Working with Private Images + +Currently, DeployStack only supports public images from Docker Hub. If you need to use private images: + +1. Make your images public on Docker Hub or [other supported registries](/docs/docker-to-iac/supported-registries) +2. Update your docker-compose.yml to reference the public images +3. Submit your repository to DeployStack + +## Environment Variables + +Please read more from our [environment variables](/docs/deploystack/docker-environment-variables) page. + +## Validation + +When you submit your repository, we perform these checks: + +1. Valid Docker Compose syntax +2. Presence of required `image` property +3. Absence of unsupported features + +## Next Steps + +- See how [One-Click Deploy](/docs/deploystack/one-click-deploy) works +- Check the [Troubleshooting](/docs/deploystack/troubleshooting) guide if you run into issues diff --git a/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/getting-started.mdx b/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/getting-started.mdx new file mode 100644 index 0000000..19d10f4 --- /dev/null +++ b/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/getting-started.mdx @@ -0,0 +1,194 @@ +--- +title: Getting Started with DeployStack +description: Start deploying Docker applications across cloud providers with DeployStack. Step-by-step guide to generating infrastructure templates from Docker configurations. +--- + +# Getting Started with DeployStack + +DeployStack offers two distinct paths to transform your Docker projects into cloud-ready deployments: a Quick Start path for immediate results, and our Recommended path for enhanced control and automation. Let's explore both approaches in detail. + +## Understanding the Two Paths + +### 🚀 Quick Start Path + +The Quick Start path is designed for developers who want to immediately make their Docker projects deployable, with minimal setup required. This approach works with your existing repository structure. + +### Recommended Path + +The Recommended path provides additional features through a `.deploystack` configuration directory and GitHub app integration. This approach enables automatic updates, environment variable management, and project customization. + +## Quick Start Path: Detailed Guide + +### For Docker Compose Projects + +#### Requirements + +- A public GitHub repository +- A `docker-compose.yml` or `docker-compose.yaml` file in your repository's root directory +- Container images must be: + - Pre-built and available in supported registries + - Publicly accessible + - Referenced using the `image` directive + +#### Step-by-Step Process + +1. **Repository Preparation** + - Ensure your `docker-compose.yml` is in the root directory + - Verify all images are publicly accessible + - Check that your compose file uses supported configuration options + +2. **Submission** + - Visit [deploystack.io/submit](https://deploystack.io/submit) + - Enter your GitHub repository URL + - Our system automatically detects your compose file + - Review the detected configuration + +3. **Template Generation** + - Infrastructure templates are generated for each supported cloud provider + - Templates are stored in our public repository + - You receive deployment button code for your README.md + +### For Docker Run Commands + +#### Requirements + +- A public GitHub repository +- A valid Docker run command that includes: + - Image name and tag + - Port mappings (if required) + - Environment variables (if needed) + - Volume mounts (if necessary) + +#### Step-by-Step Process + +1. **Command Preparation** + - Ensure your Docker run command is complete and valid + - Verify all referenced images are publicly available + - Test the command locally if possible + +2. **Submission** + - Visit [deploystack.io/submit](https://deploystack.io/submit) + - Enter your GitHub repository URL + - Paste your Docker run command + - Review the parsed configuration + +3. **Template Generation** + - Infrastructure templates are generated automatically + - Templates are optimized for each cloud provider + - You receive deployment button code + +## Recommended Path: Comprehensive Setup + +### The `.deploystack` Directory Structure + +Create a `.deploystack` directory in your repository with these components: + +```bash +.deploystack/ +├── docker-compose.yml # Your Docker Compose configuration +├── docker-run.txt # Or your Docker run command +├── env # Environment variables (optional) +└── logo.webp # Your project logo (optional) +``` + +#### Component Details + +**Docker Configuration Files**: + +- `docker-compose.yml`: Your complete Docker Compose configuration +- `docker-run.txt`: Alternative to compose file, contains your Docker run command +- Only one of these files should be present + +For more configuration options please check our [.deploystack Directory Reference](/docs/deploystack/deploystack-configuration-directory). + +### GitHub App Integration + +The [DeployStack Repository Sync](https://github.com/apps/deploystack-repository-sync) app enables: + +1. **Automatic Updates** + - Monitors changes to your Docker configurations + - Updates templates when configurations change + - Ensures templates stay in sync with your project + +2. **Installation Steps** + - Visit the GitHub app installation page + - Select your repositories + - Configure access permissions + - Verify installation + +3. **Monitoring and Updates** + - Changes to `.deploystack` directory trigger updates + - Only default branch changes are processed + - Templates are automatically regenerated + +## Behind the Scenes: How It Works + +### The docker-to-iac Module + +Our open-source [docker-to-iac](https://github.com/deploystackio/docker-to-iac) module: + +- Parses your Docker configurations +- Handles multiple cloud provider translations +- Supports various infrastructure patterns +- Maintains provider-specific optimizations + +### Template Generation Process + +1. **Configuration Analysis** + - Docker configurations are parsed + - Dependencies are identified + +2. **Provider-Specific Translation** + - Templates generated for each provider + - Provider best practices applied + - Resource mappings optimized + +3. **Template Storage** + - Templates stored in [deploy-templates](https://github.com/deploystackio/deploy-templates) + - Version controlled for tracking + - Publicly accessible + +### Deployment Button Integration + +After template generation: + +1. Visit [deploystack.io/deploy-button](https://deploystack.io/deploy-button) +2. Select your preferred button style +3. Copy the generated code +4. Add to your README.md + +## Best Practices + +### Repository Organization + +- Keep Docker configurations clean and well-documented +- Use specific version tags for images +- Document environment variable requirements +- Include clear deployment instructions + +### Configuration Management + +- Use the `.deploystack` directory for better organization +- Keep environment variables separate +- Test configurations locally + +### Deployment Strategy + +- Start with the Quick Start path if needed +- Migrate to Recommended path for better control +- Use GitHub app for automatic updates + +## Troubleshooting Common Issues + +### Template Generation + +- Verify image accessibility +- Check Docker configuration syntax +- Ensure all required ports are exposed +- Validate environment variables + +## Need Additional Help? + +- Review our detailed [Troubleshooting Guide](/docs/deploystack/troubleshooting) +- Join our active [Discord Community](https://discord.gg/UjFWwByB) +- Submit issues on GitHub to our [Feedback repository](https://github.com/deploystackio/feedback) diff --git a/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/github-application.mdx b/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/github-application.mdx new file mode 100644 index 0000000..0bfd545 --- /dev/null +++ b/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/github-application.mdx @@ -0,0 +1,69 @@ +--- +title: GitHub Application +description: Keep Docker configurations and deployment templates in sync with DeployStack's GitHub App. Updates templates automatically when files change. +--- + +# GitHub App Integration + +The DeployStack GitHub App ensures your Infrastructure as Code (IaC) templates remain synchronized with your Docker configurations. After submitting your repository to deploystack.io, install our GitHub App to enable automatic updates. + +## How It Works + +When you install the [DeployStack Repository Sync](https://github.com/apps/deploystack-repository-sync) app, it monitors specific files in your repository: + +- `.deploystack/` directory - [Contains your Docker configurations and assets](/docs/deploystack/deploystack-configuration-directory) +- `README.md` - For README.md updates + +When changes are detected in these files, the app automatically triggers an update of your IaC templates in our [deploy-templates](https://github.com/deploystackio/deploy-templates) repository. + + +Changes are only processed when they occur on your repository's **default branch**. Modifications in other branches will not trigger template, logo, config or any other updates. + + +## Installation + +1. Visit the [installation page](https://github.com/apps/deploystack-repository-sync/installations/new) +2. Select the repositories you want to monitor +3. Approve the requested permissions + +## Security & Permissions + +The app follows the principle of least privilege and requires only: + +- Read access to repository contents +- Read access to repository metadata + +These minimal permissions ensure the app can only: + +- Monitor changes to your Docker configurations +- Access basic repository information needed for template generation + +## What Gets Updated? + +When the app detects changes, it automatically updates: + +- Repository metadata in our catalog: + - Topics + - Repository Homepage + - Description +- IaC templates + - Depends on which technique (docker compose or docker run command) you choose, you can upload the `docker-compose.yml` or `docker-run.txt` in the `.deploystack` directory. Every time you update the files on your main branch (or additional branch), IaC templates will be updated automatically - [Automatic Updates](/docs/deploystack/deploystack-configuration-directory#automatic-updates). +- Environment variables + - To make it easier for a user to deploy IaC templates, it is recommended to work with environment variables. For this purpose, you can upload an `env` file and add your appropriate variables - [Environment Variables](/docs/deploystack/deploystack-configuration-directory#environment-variables). +- DeployStack Configuration +- Project / Applicaton Logo + - It is possible to upload your own logo to DeployStack catalog. To do this you need to upload a file to our directory `.deploystack`. Read more about it here: [Repository Logo](/docs/deploystack/deploystack-configuration-directory#repository-logo) + +## Managing the Integration + +You can manage or remove the integration at any time through your [GitHub Applications Settings](https://github.com/settings/installations). The app installation can be configured for specific repositories or your entire organization. + +## Next Steps + +After installing the app: + +1. Make changes to your Docker configurations in the `.deploystack` directory +2. Commit and push your changes +3. DeployStack will automatically update your deployment templates + +For details about the `.deploystack` directory structure, check our [.deploystack Directory Reference](/docs/deploystack/deploystack-configuration-directory). diff --git a/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/iac-lifecycle.mdx b/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/iac-lifecycle.mdx new file mode 100644 index 0000000..e9e551f --- /dev/null +++ b/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/iac-lifecycle.mdx @@ -0,0 +1,88 @@ +--- +title: Infrastructure as Code Lifecycle +description: Guide to how DeployStack manages Infrastructure as Code template updates, including automatic synchronization, update triggers, and version control. +--- + +# Infrastructure as Code Lifecycle + +This guide explains how DeployStack manages and updates your Infrastructure as Code (IaC) templates throughout their lifecycle. + +## Template Generation Process + +### Initial Setup + +1. Create a `.deploystack` [configuration directory](/docs/deploystack/deploystack-configuration-directory) in your repository +2. Add your Docker configuration files: + - `docker-compose.yml` for Compose configurations + - `docker-run.txt` for Docker run commands +3. Submit your repository to [deploystack.io/submit](https://deploystack.io/submit) +4. Initial IaC templates are generated and stored in our [deploy-templates](https://github.com/deploystackio/deploy-templates) repository + +### Enabling Automatic Updates + +Install the [DeployStack Repository Sync](/docs/deploystack/github-application) GitHub App to keep your templates up to date when: + +- You modify Docker configurations in the `.deploystack` directory +- Cloud providers update their IaC specifications +- DeployStack improves its template generation + +![DeployStack IaC Lifecycle](../assets/images/deploystack/iac-lifecycle.webp) + +## Update Flow + +As the app GitHub repository owner, an update flow gives you control over the generation of Infrastructure as Code (IaC) templates. The flow allows you to regenerate IaC templates by changing, for example, the `.deploystack/docker-compose.yml` file. + +All IaC templates are stored in public and open-source repository: [https://github.com/deploystackio/deploy-templates](https://github.com/deploystackio/deploy-templates). + +### Prerequisites for activating the flow + +1. You have installed the [DeployStack GitHub app](/docs/deploystack/github-application). +2. You have created the `.deploystack/docker-run.txt` or `.deploystack/docker-compose.yml` file. + +The choice between `docker-run.txt` or `docker-compose.yml` depends on the submission process used to DeployStack. When submitting to DeployStack, you can choose two methods -> Docker Run or Docker Compose. + +### Example flow + +Let's say you want to change your image tag from "deploystack/awesomeapp:v1" to "deploystack/awesomeapp:v2-next". + +![DeployStack IaC Lifecycle](../assets/images/deploystack/deploystack-iac-flow-via-github-app.webp) + +1. To do this, you will edit the file `.deploy stack/docker-run.txt` and change your new docker tag +2. GitHub will send an event to the DeployStack backend with the change of the file `.deploy stack/docker-run.txt` because you have the DeployStack GitHub app installed. +3. DeployStack backend validates the change, and if everything test passes +4. By using [docker-to-iac module](https://github.com/deploystackio/docker-to-iac), DeployStack backend will generate the new IaC templates for your application and store them in our repository [https://github.com/deploystackio/deploy-templates](https://github.com/deploystackio/deploy-templates) + +## Update Triggers + +Your IaC templates are automatically updated in these scenarios: + +### Repository Changes + +When you modify files in your repository's default branch: + +- Changes to `docker-compose.yml` or `docker-run.txt` in `.deploystack` directory +- Updates to repository metadata + +### Provider Updates + +Templates are regenerated when: + +- Cloud providers modify their IaC specifications +- New provider features become available +- Provider API requirements change + +### System Updates + +DeployStack initiates template updates when: + +- The docker-to-iac module receives improvements +- New template optimizations are available +- Bug fixes are released + +## Template Versioning + +All template updates are version controlled in our [deploy-templates repository](https://github.com/deploystackio/deploy-templates), allowing you to: + +- Track template changes over time +- Review modification history +- Understand update triggers diff --git a/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/index.mdx b/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/index.mdx new file mode 100644 index 0000000..58ffd00 --- /dev/null +++ b/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/index.mdx @@ -0,0 +1,23 @@ +--- +title: DeployStack Documentation +description: Official DeployStack documentation - Learn how to automate Docker Compose and run deployments across cloud providers. Clear guides and technical references for effective deployment automation. +menuTitle: DeployStack +--- + +# DeployStack - Open Source Cloud Deployment Guide + +DeployStack helps you deploy Docker Compose and Docker Run applications across different cloud providers by automatically generating Infrastructure as Code templates. Our documentation guides you through using DeployStack effectively. + +## Documentation Sections + +- [Getting Started](/docs/deploystack/getting-started.md) - Quick introduction and first steps +- [Docker Compose Requirements](/docs/deploystack/docker-compose-requirements.md) - Learn about supported configurations +- [One-Click Deploy](/docs/deploystack/one-click-deploy.md) - Learn about deployment automation +- [Troubleshooting](/docs/deploystack/troubleshooting.md) - Resolve common issues + +## Additional Resources + +- [Docker-to-IaC Module Documentation](/docs/docker-to-iac/index.md) +- [Join our Discord](https://discord.gg/UjFWwByB) +- [Visit DeployStack](https://deploystack.io) + diff --git a/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/multiple-branches.mdx b/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/multiple-branches.mdx new file mode 100644 index 0000000..ddb2f35 --- /dev/null +++ b/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/multiple-branches.mdx @@ -0,0 +1,150 @@ +--- +title: Branch Strategy +description: Guide to implementing multi-branch deployment strategies with DeployStack, enabling version-specific deployments and automated template management. +--- + +# Branch Strategy + +DeployStack's branch strategy allows you to maintain and deploy multiple versions of your application simultaneously. This is particularly valuable when you're evolving your application while maintaining stable versions for production users. + +## The Multi-Version Journey + +### Starting Point: Default Branch + +Every repository starts with its default branch (typically `main` or `master`). This branch: + +- Always generates Infrastructure as Code templates +- Cannot be excluded from template generation +- Has implicit `priority: 0` in deployment options +- Can be changed through your repository settings + +When you change your default branch in GitHub: + +- DeployStack automatically detects the change - you need to install [DeployStack GitHub App](/docs/deploystack/github-application) +- Regenerates templates for the new default branch +- Updates all deployment buttons + +### Growing Your Application: Adding New Versions + +As your application evolves, you might want to: + +- Develop a new major version with breaking changes +- Maintain an LTS (Long Term Support) version +- Test new features with early adopters + +This is where branch configurations become powerful. You can maintain up to 5 active branches, each with: + +- Its own Docker configuration +- Separate environment variables +- Independent deployment options + +For example, when developing version 2 of your application: + +```yaml +deployment: + branches: + v2: + label: "Version 2 Beta" + description: "Next generation features" + priority: 1 +``` + +### Branch-Specific Configurations + +Each branch can have its own `.deploystack` directory with standard configuration files. First, create the directories on your default branch: + +```bash +# Default branch configuration + +your-repository/ +└── .deploystack/ + ├── config.yml + ├── docker-compose.yml + └── env +``` + +```bash +# v2 branch configuration + +your-repository/ +└── .deploystack/ + ├── config.yml + ├── docker-compose.yml + └── env +``` + +This structure allows you to: + +- Use different Docker configurations per branch +- Maintain separate environment variables +- Modify service configurations independently +- Keep each version's deployment parameters isolated + +Remember: The DeployStack GitHub App only monitors the standard filenames: check [.deploystack Directory Reference for more info](/docs/deploystack/deploystack-configuration-directory) + +## Real-World Example + +Let's say you're maintaining a web application: + +```yaml +application: + name: "MyWebApp" + description: "Modern web application stack" + +deployment: + branches: + v1-lts: + label: "v1 LTS" + description: "Stable v1.x release with long-term support" + priority: 1 + v2-beta: + label: "v2 Beta" + description: "New architecture with enhanced features" + priority: 2 + experimental: + label: "Edge" + description: "Latest experimental features" + priority: 3 +``` + +Each branch can have different Docker configurations: + +- `main` branch (v1.x stable): + + ```yaml + # docker-compose.yml + services: + web: + image: myapp:1.5 + ``` + +- `v2-beta` branch: + + ```yaml + # docker-compose.yml + services: + web: + image: myapp:2.0-beta + ``` + +## Benefits for Your Users + +This strategy allows your users to: + +- Choose the version that best fits their needs +- Test new versions while maintaining production deployments +- Safely transition between versions at their own pace +- Deploy LTS versions for stability +- Try experimental features in isolation + +## Important Notes + +- Maximum of 5 active branches supported +- Each branch can have unique Docker configurations +- Default branch can be changed (switch to another branch and make it default) but not excluded +- Branch configurations ([DeployStack config file](/docs/deploystack/deploystack-config-file)) must be in the default branch +- All branches are automatically monitored for changes +- Template regeneration happens automatically when: + - Branch content changes + - Default branch is changed + - Configuration is updated diff --git a/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/one-click-deploy.mdx b/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/one-click-deploy.mdx new file mode 100644 index 0000000..8cf961e --- /dev/null +++ b/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/one-click-deploy.mdx @@ -0,0 +1,157 @@ +--- +title: One-Click Deploy +description: Technical docs for DeployStack's one-click deployment feature. Covers infrastructure template generation, cloud provider integration, and button configuration. +--- + +# One-Click Deploy + +DeployStack leverages existing deployment technologies from cloud providers to make application deployment as straightforward as possible. + +## How One-Click Deploy Works + +When you submit your repository to [deploystack.io/submit](https://deploystack.io/submit), we: + +1. Generate Infrastructure as Code (IaC) templates for [supported cloud providers](/docs/docker-to-iac/index) +2. Store these templates in our [deploy-templates repository](https://github.com/deploystackio/deploy-templates) +3. Create provider-specific deployment buttons for your README.md -> by [deploystack.io/deploy-button](https://deploystack.io/deploy-button) + +## Template Generation and Storage + +### Repository Structure + +All generated templates are stored in the [deploystackio/deploy-templates](https://github.com/deploystackio/deploy-templates) repository using this organization: + +- Each project gets its own subfolder and branch +- Naming convention: `-` (lowercase) +- Example: `microsoft-vscode` for Microsoft's VS Code repository + +### Branch Strategy + +We create a dedicated branch for each project to support one-click deployment functionality: + +- Branch name matches the subfolder name +- Contains all necessary IaC templates and configurations +- Enables direct integration with cloud provider deployment systems + +## Cloud Provider Integration + +### Current Providers + +We integrate with cloud providers' native deployment systems. For example: + +- **DigitalOcean**: Uses the "Deploy to DigitalOcean" functionality as documented in their [official guide](https://docs.digitalocean.com/products/app-platform/how-to/add-deploy-do-button/) +- **Kubernetes**: Generates Helm charts that can be deployed to any Kubernetes cluster +- Check [supported cloud providers](/docs/docker-to-iac/index) for full list + +### Provider-Specific Templates + +Each cloud provider may require specific template formats: + +- AWS CloudFormation templates +- DigitalOcean App Spec +- Render Blueprints +- And more based on provider requirements +- Kubernetes Helm charts with all necessary templates + +## Using Deploy Buttons + +After template generation, you'll receive HTML/Markdown code for deployment buttons by visitig the [deploystack.io/deploy-button](https://deploystack.io/deploy-button) page. + +There are two options you can chose from. The main difference is the deploy url. For the mode "Deploy via DeployStack" the deploy address points to the deploystack.io/deploy endpoint, where HTTP status code 302 redirects to the cloud provider one-click deploy endpoint. + +In the example below with render: + +```markdown +1. -> https://deploystack.io/deploy/microsoft-vscode?provider=rnd&language=rnd +2. -> HTTP 302 REDIRECT +3. -> https://render.com/deploy?repo=https://github.com/deploystackio/deploy-templates/tree/microsoft-vscode +``` + +### Deploy via DeployStack + +Link via deploystack deploy endpoint. + +- auto update on One-Click deploy links: if the provider's deploy url changes, we will update. +- future cloud provider support out of the box: The endpoint makes it easier for us to integrate with additional providers, which benefits your users. +- deploy statistics for your app: We collect anonymized statistics to show the number of deployments your application has had, similar to npm download statistics. + +#### Example Markdown Deploy via DeployStack + +- static deploy links: if the cloud provider changes the one-click deploy url, the functionality will also be broken. You have to update your `README.md` manually. +- no statistics collection possible: you will never know how many people use your project :) + +```markdown title="README.md" +## ⚡ One-Click Deploy + +| Cloud Provider | Deploy Button | +|---------------|---------------| +| Render | | +``` + +### Deploy Standalone + +Direct link to Cloud Provider to enable One-Click depoy. + +#### Example Markdown Deploy Standalone + +```markdown title="README.md" +## ⚡ One-Click Deploy + +| Cloud Provider | Deploy Button | +|---------------|---------------| +| Render | | +``` + +## License and Usage + +All generated templates are available under the MIT License: + +- Full license text available in the [deploy-templates repository](https://github.com/deploystackio/deploy-templates/blob/main/LICENSE) +- Free to use, modify, and distribute +- No warranty provided + +## Extending Provider Support + +Want to add support for another cloud provider? You can: + +1. Contribute to the [docker-to-iac module](https://github.com/deploystackio/docker-to-iac) +2. Add a new provider parser +3. Implement the necessary template generation logic + +Benefits of contributing: + +- All existing projects in our catalog automatically get templates for the new provider +- The open-source community benefits from broader deployment options +- Your provider becomes part of the one-click deployment ecosystem + +## Technical Implementation Details + +The one-click deployment process: + +1. User clicks deploy button +2. Cloud provider loads template from our repository's specific branch +3. Provider's deployment system processes the template +4. Application gets deployed according to specifications + +## Validation and Security + +For each deployment: + +- Templates are version controlled +- Source code is publicly accessible +- Infrastructure specifications are transparent +- No sensitive data is stored in templates + +## Future Enhancements + +We're continuously working to: + +- Add more cloud providers +- Improve template generation +- Enhance deployment options +- Support more complex configurations + +## Next Steps + +- Visit our [Discord community](https://discord.gg/UjFWwByB) for help +- Consider [contributing](https://github.com/deploystackio/docker-to-iac) to add more providers diff --git a/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/troubleshooting.mdx b/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/troubleshooting.mdx new file mode 100644 index 0000000..15bb2aa --- /dev/null +++ b/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/troubleshooting.mdx @@ -0,0 +1,151 @@ +--- +title: Troubleshooting DeployStack Issues +description: Technical solutions for common DeployStack deployment issues. Find answers to repository submission errors, license restrictions, and Docker Compose validation problems. +--- + +# Troubleshooting + +This guide helps you resolve common issues that might occur when submitting your repository to DeployStack. + +## Invalid GitHub Repository URL + +This error occurs when the submitted URL doesn't match the expected GitHub repository URL format. + +**Common causes:** + +- Missing 'github.com' in the URL +- Including query parameters + +**Solution:** +Use the standard GitHub repository URL format: + +```bash +https://github.com/username/repository +``` + +## Repository License Not Permitted + +We don't support certain licenses to protect both our users and our service. Here's what we currently don't support: + +| License Type | Reason for Restriction | +|-------------|------------------------| +| No License | Without a license, the code defaults to exclusive copyright, making it legally risky to use or deploy | +| Proprietary License | These licenses typically restrict redistribution and modification rights | +| Commons Clause | This addition to licenses restricts commercial use of the software | +| Shared Source | These licenses often include terms that limit deployment and distribution | +| Custom License | Custom licenses require individual legal review and may contain problematic terms | + +**Other Restrictions:** + +- Licenses containing "proprietary" terms +- Licenses with Commons Clause additions +- Licenses marked as "shared source" +- Any repository without clear license information + +**Solution:** + +Ensure your repository: + +- Uses a widely accepted open-source license (MIT, Apache, GPL, etc.) +- Has clear license information in the repository +- If you can, change your repository license to a supported one +- For special cases, whitelist requests can be submitted via [Discord](https://discord.gg/UjFWwByB) or Twitter DM + +## Invalid Base64 Encoding for Docker File + +This error occurs during our internal processing of your docker-compose file. + +**Common causes:** + +- File encoding issues +- Special characters in the file +- File corruption + +**Solution:** + +- Verify your docker-compose file uses UTF-8 encoding +- Remove any special characters +- Try re-creating the file if issues persist + +## Invalid Docker Compose File + +The submitted docker-compose file doesn't meet the required format or contains unsupported features. + +**Common causes:** + +- Invalid YAML syntax +- Unsupported Docker Compose version +- Missing required fields +- Using unsupported features + +**Solution:** + +- Validate your docker-compose file syntax +- Check our [Docker Compose Requirements](/docs/deploystack/docker-compose-requirements) page +- Ensure you're using supported features only + +## Error Converting Docker Compose to IaC + +This error occurs when our system cannot convert your docker-compose configuration to Infrastructure as Code templates. + +**Common causes:** + +- Unsupported service configurations +- Complex dependencies +- Resource definitions that can't be mapped to cloud provider services + +**Solution:** + +- Simplify your docker-compose configuration +- Review our [supported features documentation](/docs/docker-to-iac/supported-docker-compose-variables) +- Ensure all services use supported configurations + +## Error Listing Services from Docker Compose + +The system couldn't properly parse the services defined in your docker-compose file. + +**Common causes:** + +- Malformed service definitions +- Missing required service properties +- Invalid service configurations + +**Solution:** + +- Verify each service has the required `image` property +- Check service definitions follow the correct format +- Remove any unsupported service configurations + +## Internal Server Error + +This indicates an unexpected error in our validation process. + +**What it means:** + +- The error is on our end +- The issue isn't related to your repository or configuration +- We needs to investigate + +**What to do:** + +1. Try your submission again after a few minutes +2. If the error persists, join our [Discord community](https://discord.gg/UjFWwByB) +3. Report the issue with: + - Your repository URL + - Timestamp of the error + - Any error messages you received + +## General Troubleshooting Tips + +1. Validate your docker-compose file locally before submission +2. Ensure your repository meets all [requirements](/docs/deploystack/docker-compose-requirements) +3. Check that all services use supported configurations +4. Verify your repository is public and accessible + +## Need More Help? + +If you're still experiencing issues: + +- Join our [Discord community](https://discord.gg/UjFWwByB) +- Check our [Docker Compose Requirements](/docs/deploystack/docker-compose-requirements) +- Review [supported features](/docs/docker-to-iac/supported-docker-compose-variables) diff --git a/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/api.mdx b/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/api.mdx new file mode 100644 index 0000000..8aaff08 --- /dev/null +++ b/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/api.mdx @@ -0,0 +1,790 @@ +--- +title: docker-to-iac module API +description: Here's everything you need to know about our docker-to-iac module - from listing available cloud providers to converting your Docker setup into deployable code. +--- + +# docker-to-iac module API list + +In this page you will find all possible APIs for package docker-to-iac. + +## List all Parser + +To list all available parsers, please use the `listAllParsers()` method. + +### Example + +```typescript +import { listAllParsers } from '@deploystack/docker-to-iac'; + +const parsers = listAllParsers(); + +console.log('Available Parsers:'); +console.log(parsers); +``` + +#### Output + +```json +[ + { + providerWebsite: 'https://aws.amazon.com/cloudformation/', + providerName: 'Amazon Web Services', + providerNameAbbreviation: 'AWS', + languageOfficialDocs: 'https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html', + languageAbbreviation: 'CFN', + languageName: 'AWS CloudFormation', + defaultParserConfig: { files: [Array], cpu: 512, memory: '1GB' } + }, + { + providerWebsite: 'https://render.com/docs', + providerName: 'Render', + providerNameAbbreviation: 'RND', + languageOfficialDocs: 'https://docs.render.com/infrastructure-as-code', + languageAbbreviation: 'RND', + languageName: 'Render Blue Print', + defaultParserConfig: { + files: [Array], + subscriptionName: 'starter', + region: 'oregon', + diskSizeGB: 10 + } + }, + { + providerWebsite: 'https://www.digitalocean.com/', + providerName: 'DigitalOcean', + providerNameAbbreviation: 'DO', + languageOfficialDocs: 'https://docs.digitalocean.com/products/app-platform/', + languageAbbreviation: 'DOP', + languageName: 'DigitalOcean App Spec', + defaultParserConfig: { files: [Array], region: 'nyc', subscriptionName: 'basic-xxs' } + }, + { + providerWebsite: 'https://helm.sh/', + providerName: 'Kubernetes', + providerNameAbbreviation: 'K8S', + languageOfficialDocs: 'https://helm.sh/docs/', + languageAbbreviation: 'HELM', + languageName: 'Helm Chart', + defaultParserConfig: { + files: [Array], + cpu: '100m', + memory: '128Mi' + } + }, + { + providerWebsite: 'https://www.digitalocean.com/', + providerName: 'DigitalOcean', + providerNameAbbreviation: 'DO', + languageOfficialDocs: 'https://docs.digitalocean.com/products/app-platform/', + languageAbbreviation: 'DOP', + languageName: 'DigitalOcean App Spec', + defaultParserConfig: { files: [Array], region: 'nyc', subscriptionName: 'basic-xxs' } + } +] +``` + +**Note the files array**: that's because we have a [multi file strategy](/docs/docker-to-iac/multi-file-configuration). + +### Type + +```typescript +listAllParsers(): ParserInfo[] +``` + +## Get Parser Info + +If you want to extract the `defaultParserConfig` object from a parser, the `getParserInfo` method is the most suitable for this. + +### Example + +```typescript +import { getParserInfo } from '@deploystack/docker-to-iac'; + +const awsInfo = getParserInfo('CFN'); + +console.log('Available Parsers:'); +console.log(awsInfo); +``` + +#### Output + +```json +{ + providerWebsite: 'https://aws.amazon.com/cloudformation/', + providerName: 'Amazon Web Services', + providerNameAbbreviation: 'AWS', + languageOfficialDocs: 'https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html', + languageAbbreviation: 'CFN', + languageName: 'AWS CloudFormation', + defaultParserConfig: { + files: [ + { + path: 'aws-cloudformation.cf.yml', + templateFormat: 'yaml', + isMain: true, + description: 'AWS CloudFormation template' + } + ], + cpu: 512, + memory: '1GB' + } +} +``` + +### Type + +```typescript +getParserInfo(languageAbbreviation: string): ParserInfo +``` + +## Translate API + +Translate Docker configurations (both Docker run commands and docker-compose.yml files) into your chosen Infrastructure as Code language. + +### Function Signature + +```typescript +translate(input: string, options: { + source: 'run' | 'compose', + target: string, + templateFormat?: TemplateFormat, + environmentVariableGeneration?: EnvironmentVariableGenerationConfig; + environmentVariables?: Record; + persistenceKey?: string; + serviceConnections?: ServiceConnectionsConfig; +}): TranslationResult +``` + +Where `TranslationResult` has the structure: + +```typescript +interface TranslationResult { + files: { + [path: string]: FileOutput + }; + serviceConnections?: ResolvedServiceConnection[]; +} + +interface FileOutput { + content: string; + format: TemplateFormat; + isMain?: boolean; +} +``` + +### Examples + +#### Translating Docker Compose + +```javascript +import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs'; +import { join, dirname } from 'path'; +import { translate } from '@deploystack/docker-to-iac'; + +const dockerComposeContent = readFileSync('path/to/docker-compose.yml', 'utf8'); + +const result = translate(dockerComposeContent, { + source: 'compose', + target: 'CFN', + templateFormat: 'yaml' +}); + +// Access individual file contents +console.log(`Generated ${Object.keys(result.files).length} files:`); +Object.keys(result.files).forEach(path => { + console.log(`- ${path}`); +}); + +// Write files to disk preserving directory structure +Object.entries(result.files).forEach(([path, fileData]) => { + const fullPath = join('output', path); + const dir = dirname(fullPath); + + if (!existsSync(dir)) { + mkdirSync(dir, { recursive: true }); + } + + writeFileSync(fullPath, fileData.content); +}); +``` + +#### Translating Docker Run Command + +```javascript +import { translate } from '@deploystack/docker-to-iac'; +import { writeFileSync, mkdirSync, existsSync } from 'fs'; +import { join, dirname } from 'path'; + +const dockerRunCommand = 'docker run -d -p 8080:80 nginx:latest'; + +const result = translate(dockerRunCommand, { + source: 'run', + target: 'RND', + templateFormat: 'yaml' +}); + +console.log(result) + +// Access and save all generated files +Object.entries(result.files).forEach(([path, fileData]) => { + const fullPath = join('output', path); + const dir = dirname(fullPath); + + if (!existsSync(dir)) { + mkdirSync(dir, { recursive: true }); + } + + writeFileSync(fullPath, fileData.content); + console.log(`Created: ${path}`); +}); +``` + +#### Translating Docker Compose to Helm Chart + +```javascript +import { translate } from '@deploystack/docker-to-iac'; +import { writeFileSync, mkdirSync, existsSync } from 'fs'; +import { join, dirname } from 'path'; + +const dockerComposeContent = ` +version: '3' +services: + web: + image: nginx:latest + ports: + - "80:80" + db: + image: postgres:13 + environment: + POSTGRES_USER: myuser + POSTGRES_PASSWORD: mypassword + POSTGRES_DB: myapp +`; + +const result = translate(dockerComposeContent, { + source: 'compose', + target: 'HELM', + templateFormat: 'yaml' +}); + +// Access and save all generated files to create a complete Helm Chart +Object.entries(result.files).forEach(([path, fileData]) => { + const fullPath = join('helm-chart', path); + const dir = dirname(fullPath); + + if (!existsSync(dir)) { + mkdirSync(dir, { recursive: true }); + } + + writeFileSync(fullPath, fileData.content); + console.log(`Created: ${path}`); +}); +``` + +#### Example Output (Partial - Chart.yaml) + +```yaml +apiVersion: v2 +name: deploystack-app +description: A Helm chart for DeployStack application generated from Docker configuration +type: application +version: 0.1.0 +appVersion: 1.0.0 +maintainers: + - name: DeployStack + email: hello@deploystack.io +dependencies: + - name: db + repository: https://charts.bitnami.com/bitnami + version: ^12.0.0 + condition: dependencies.db.enabled +``` + +#### Configuring Service Connections + +```javascript +import { translate } from '@deploystack/docker-to-iac'; + +const dockerComposeContent = ` +version: "3" +services: + db: + image: mariadb:latest + environment: + - MYSQL_ROOT_PASSWORD=rootpass + app: + image: node:alpine + environment: + - DATABASE_HOST=db # This will be transformed +`; + +const result = translate(dockerComposeContent, { + source: 'compose', + target: 'DOP', // DigitalOcean App Platform + templateFormat: 'yaml', + serviceConnections: { + mappings: [ + { + fromService: 'app', // Service that needs to connect + toService: 'db', // Service to connect to + environmentVariables: [ // Env vars that reference the service + 'DATABASE_HOST' + ] + } + ] + } +}); + +// The result will include transformed service references: +console.log(result.serviceConnections); +``` + +### Example Output (AWS CloudFormation) + +```yaml +{ + files: { + 'render.yaml': { + content: 'services:\n' + + ' - name: default\n' + + ' type: web\n' + + ' env: docker\n' + + ' runtime: image\n' + + ' image:\n' + + ' url: docker.io/library/nginx:latest\n' + + ' startCommand: ""\n' + + ' plan: starter\n' + + ' region: oregon\n' + + ' envVars:\n' + + ' - key: PORT\n' + + ' value: "80"\n', + format: 'yaml', + isMain: true + } + } +} +Created: render.yaml +``` + +#### Translation with Environment Variable Generation + +```typescript +import { translate } from '@deploystack/docker-to-iac'; + +// Environment variable configuration +const envConfig = { + 'library/mariadb': { + versions: { + '*': { + environment: { + 'MYSQL_ROOT_PASSWORD': { + type: 'password', + length: 16 + }, + 'MYSQL_DATABASE': { + type: 'string', + length: 12, + pattern: 'lowercase' + } + } + } + } + } +}; + +const translatedConfig = translate(dockerComposeContent, { + source: 'compose', + target: 'CFN', + templateFormat: 'yaml', + environmentVariableGeneration: envConfig +}); +``` + +### Parameters + +#### `input: string` + +For Docker Compose: The contents of your docker-compose.yml file +For Docker run: The complete docker run command + +#### `options.source: 'run' | 'compose'` + +Specifies the input type: + +- `'run'` - For Docker run commands +- `'compose'` - For Docker Compose files + +#### `options.target: string` + +The IaC language to translate to. Currently supported targets: +Please see the sidebar on the left, section Parsers. + +#### `options.templateFormat?: TemplateFormat` + +Optional. The desired output format: + +- `'json'` - JavaScript Object Notation +- `'yaml'` - YAML format +- `'text'` - Plain text + +> [!IMPORTANT] +> Not all template formats are valid for every IaC language. For example, AWS CloudFormation only accepts YAML or JSON formats. Choose a format compatible with your target IaC language. + +#### `options.environmentVariableGeneration?: EnvironmentVariableGenerationConfig` + +Optional. Configuration for generating environment variable values. Structure: + +```typescript +type EnvironmentVariableGenerationConfig = { + [imageName: string]: { + versions: { + [version: string]: { + environment: { + [variableName: string]: { + type: 'password' | 'string' | 'number'; + length?: number; + pattern?: 'uppercase' | 'lowercase' | 'normal'; + min?: number; // For number type + max?: number; // For number type + } + } + } + } + } +} +``` + +Generation types: + +- `password`: Generates a secure random password +- `string`: Generates a random string +- `number`: Generates a random number within specified range + +Patterns (for string type): + +- `uppercase`: Only uppercase characters +- `lowercase`: Only lowercase characters +- `normal`: Mixed case with numbers + +Version matching: + +- Use exact versions (e.g., "10.5") +- Use "*" for all versions +- Use "latest" for latest version + +> [!IMPORTANT] +> Environment variables in your docker-compose.yml must use the `${VARIABLE_NAME}` syntax to be processed by the generator. + +#### `environmentVariables?: Record` + +Optional. The docker-to-iac module supports passing environment variables from `.env` files to your Infrastructure as Code templates. This feature allows you to manage configuration values separately from your Docker configurations and maintain consistency across deployments. + +```typescript +import { translate, parseEnvFile } from '@deploystack/docker-to-iac'; +import { readFileSync } from 'fs'; + +// Read and parse the .env file +const envContent = readFileSync('.env', 'utf-8'); +const envVariables = parseEnvFile(envContent); + +const result = translate(dockerConfig, { + source: 'run', // or 'compose' + target: 'RND', // or other supported targets + templateFormat: 'yaml', + environmentVariables: envVariables +}); +``` + +#### `options.persistenceKey?: string` + +Optional. The `persistenceKey` parameter allows you to maintain consistent variable values across multiple template generations. + +#### `options.serviceConnections?: ServiceConnectionsConfig` + +Optional. Configure service-to-service communications by defining which environment variables reference other services. + +```typescript +type ServiceConnectionsConfig = { + mappings: Array<{ + fromService: string; // Service that needs to connect + toService: string; // Service to connect to + environmentVariables: string[]; // Environment variables that reference the service + property?: string; // Connection property type (connectionString, hostport, etc.) + }> +}; +``` + +This option is currently supported by: + +- Render.com (RND): Uses Blueprint's `fromService` syntax +- DigitalOcean App Platform (DOP): Uses direct service names +- Kubernetes Helm Charts (HELM): Uses Kubernetes DNS service discovery + +Example: + +```javascript +serviceConnections: { + mappings: [ + { + fromService: 'frontend', + toService: 'api', + environmentVariables: ['API_URL'], + property: 'hostport' + }, + { + fromService: 'app', + toService: 'db', + environmentVariables: ['DATABASE_URL'], + property: 'connectionString' + } + ] +} +``` + +### Return Value + +Returns the translated Infrastructure as Code template and any resolved service connections: + +```typescript +{ + files: { + // Generated IaC template files with paths as keys + 'render.yaml': { content: '...', format: 'yaml', isMain: true } + }, + serviceConnections: [ + { + fromService: 'app', + toService: 'db', + variables: { + 'DATABASE_HOST': { + originalValue: 'db', + transformedValue: 'db' // Transformed as appropriate for the provider + } + } + } + ] +} +``` + +## List Services API + +Extract service configurations from either Docker run commands or docker-compose.yml files as structured JSON objects. + +### Function Signature + +```typescript +listServices(content: string, options: ListServicesOptions): { [key: string]: ServiceConfig } + +type ListServicesOptions = { + source: 'compose' | 'run'; + environmentVariableGeneration?: EnvironmentVariableGenerationConfig; + environmentVariables?: Record; + persistenceKey?: string; +}; +``` + +### Examples + +#### Listing Docker Compose Services with Environment Variables + +```javascript +import { readFileSync } from 'fs'; +import { listServices, parseEnvFile } from '@deploystack/docker-to-iac'; + +const dockerComposeContent = readFileSync('path/to/docker-compose.yml', 'utf8'); +const envContent = readFileSync('.env', 'utf-8'); +const envVariables = parseEnvFile(envContent); + +const services = listServices(dockerComposeContent, { + source: 'compose', + environmentVariables: envVariables +}); + +console.log(services); +``` + +##### Output with Environment Variables + +```json +{ + "db": { + "image": "mariadb:11.2", + "ports": [], + "command": "mariadbd --character-set-server=utf8mb4 --collation-server=utf8mb4_bin", + "restart": "unless-stopped", + "volumes": [{"host": "db", "container": "/var/lib/mysql"}], + "environment": { + "MYSQL_ROOT_PASSWORD": "mysecretpassword", + "MYSQL_USER": "myuser", + "MYSQL_PASSWORD": "mysecretpassword", + "MYSQL_DATABASE": "mydatabase" + } + } +} +``` + +#### Listing Docker Run Services + +```javascript +import { listServices } from '@deploystack/docker-to-iac'; + +const dockerRunCommand = 'docker run -d -p 8080:80 -e NODE_ENV=production nginx:latest'; + +const services = listServices(dockerRunCommand, { + source: 'run' +}); + +console.log(services); +``` + +##### Output + +```json +{ + "service": { + "image": "nginx:latest", + "ports": ["8080:80"], + "environment": { + "NODE_ENV": "production" + } + } +} +``` + +### Options + +#### `content: string` + +The input content to parse: + +- For Docker Compose: The contents of your docker-compose.yml file +- For Docker run: The complete docker run command + +#### `options.source: 'run' | 'compose'` + +Specifies the input type: + +- `'run'` - For Docker run commands +- `'compose'` - For Docker Compose files + +#### `options.environmentVariables?: Record` + +Optional. Environment variables from a `.env` file or other source. Used to substitute variables in the format `${VARIABLE_NAME}` in your Docker configuration. + +Example: + +```javascript +const envVariables = { + 'DB_PASSWORD': 'mysecretpassword', + 'DB_USERNAME': 'myuser', + 'DB_DATABASE': 'mydatabase' +}; +``` + +#### `options.environmentVariableGeneration?: EnvironmentVariableGenerationConfig` + +Optional. Configuration for automatically generating environment variable values. Structure: + +```typescript +type EnvironmentVariableGenerationConfig = { + [imageName: string]: { + versions: { + [version: string]: { + environment: { + [variableName: string]: { + type: 'password' | 'string' | 'number'; + length?: number; + pattern?: 'uppercase' | 'lowercase' | 'normal'; + min?: number; // For number type + max?: number; // For number type + } + } + } + } + } +} +``` + +Example: + +```javascript +const envGeneration = { + 'library/mariadb': { + versions: { + '*': { + environment: { + 'MYSQL_ROOT_PASSWORD': { + type: 'password', + length: 16 + }, + 'MYSQL_DATABASE': { + type: 'string', + length: 12, + pattern: 'lowercase' + } + } + } + } + } +}; +``` + +#### `options.persistenceKey?: string` + +Optional. A unique key to maintain consistent generated environment variables across multiple calls to `listServices` or `translate`. + +### Return Value + +Returns an object where: + +- Keys are service names +- Values are service configurations containing: + - `image`: Docker image name and tag + - `ports`: Array of port mappings + - `command`: Custom command (if specified) + - `restart`: Restart policy (if specified) + - `volumes`: Array of volume mappings (if specified) + - `environment`: Object of environment variables + +## Parse Environment File + +Parse a `.env` file content into a key-value object using the `parseEnvFile()` method. The method handles basic environment file syntax including comments and quoted values. + +### Example + +```typescript +import { parseEnvFile } from '@deploystack/docker-to-iac'; + +const envContent = ` +# Database settings +DB_HOST=localhost +DB_USER="admin" +DB_PASS='secretpass' +# Comment line +NUMBERS=123456 +QUOTED="value=with=equals" +`; + +const envVars = parseEnvFile(envContent); + +console.log('Parsed Environment Variables:'); +console.log(envVars); +``` + +#### Output + +```json +{ + "DB_HOST": "localhost", + "DB_USER": "admin", + "DB_PASS": "secretpass", + "NUMBERS": "123456", + "QUOTED": "value=with=equals" +} +``` + +### Type + +```typescript +parseEnvFile(content: string): Record +``` diff --git a/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/example-of-a-new-parser.mdx b/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/example-of-a-new-parser.mdx new file mode 100644 index 0000000..571f608 --- /dev/null +++ b/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/example-of-a-new-parser.mdx @@ -0,0 +1,383 @@ +--- +title: Example of a New Parser +description: Example code for adding a new parser to docker-to-iac, supporting both Docker run commands and Docker Compose files, with multi-file output and service connections +--- + +# Adding a New Parser + +> [!TIP] +> Thank you for your interest in collaborating! The docker-to-iac module will remain open source forever, helping simplify deployments across cloud providers without vendor lock-in. + +## Parser Implementation + +Create a new file inside `src/parsers/new-provider.ts`: + +```typescript +import { + BaseParser, + ParserInfo, + TemplateFormat, + ParserConfig, + FileOutput, + DockerImageInfo +} from './base-parser'; +import { ApplicationConfig } from '../types/container-config'; +import { parsePort } from '../utils/parsePort'; +import { parseCommand } from '../utils/parseCommand'; + +// Define default configuration for your parser +const defaultParserConfig: ParserConfig = { + files: [ + { + path: 'awesome-iac.yaml', + templateFormat: TemplateFormat.yaml, + isMain: true, + description: 'Main IaC configuration file' + }, + { + path: 'templates/resources.yaml', + templateFormat: TemplateFormat.yaml, + description: 'Additional resources configuration' + } + ], + cpu: 512, + memory: '1GB', + region: 'default-region', + subscriptionName: 'basic-tier' +}; + +// Optional: Add helper functions for your specific provider +function getNewProviderServiceType(imageInfo: DockerImageInfo): string { + // Logic to determine service type based on image + // Example: Check if it's a database, web service, etc. + return 'web-service'; // Default type +} + +// Optional: Add function to determine if an image is a managed service +function isNewProviderManagedService(imageInfo: DockerImageInfo): boolean { + // Check if this image should be handled as a managed service + const imageUrl = `${imageInfo.repository}:${imageInfo.tag || 'latest'}`; + return imageUrl.includes('postgres') || imageUrl.includes('redis'); +} + +class NewProviderParser extends BaseParser { + // Multi-file implementation - required by BaseParser + parseFiles(config: ApplicationConfig): { [path: string]: FileOutput } { + // Initialize result containers + const services: Array = []; + const managedServices: Array = []; + + // Track service mappings for managed services + const managedServiceMap = new Map(); + + // First pass: identify and register managed services + for (const [serviceName, serviceConfig] of Object.entries(config.services)) { + if (isNewProviderManagedService(serviceConfig.image)) { + // Create a managed service instead of a regular service + const managedName = `${serviceName}-managed`; + + // Track the mapping for service connections later + managedServiceMap.set(serviceName, managedName); + + // Add to managed services collection + managedServices.push({ + name: managedName, + type: getNewProviderServiceType(serviceConfig.image), + // Add provider-specific managed service properties + plan: defaultParserConfig.subscriptionName + }); + + // Skip further processing of this service + continue; + } + + // Regular services will be processed in the second pass + } + + // Second pass: process regular services with their connections + for (const [serviceName, serviceConfig] of Object.entries(config.services)) { + // Skip managed services already processed + if (managedServiceMap.has(serviceName)) { + continue; + } + + // Extract ports from service configuration + const ports = new Set(); + if (serviceConfig.ports) { + serviceConfig.ports.forEach(port => { + if (typeof port === 'object' && port !== null) { + ports.add(port.container); + } else { + const parsedPort = parsePort(port); + if (parsedPort) { + ports.add(parsedPort); + } + } + }); + } + + // Prepare basic service definition + const service: any = { + name: serviceName, + type: getNewProviderServiceType(serviceConfig.image), + image: serviceConfig.image, + command: parseCommand(serviceConfig.command), + environment: [] + }; + + // Add ports if available + if (ports.size > 0) { + service.ports = Array.from(ports); + } + + // Process service connections if available + if (config.serviceConnections) { + // First add regular environment variables + for (const [key, value] of Object.entries(serviceConfig.environment)) { + // Check if this variable is handled by service connections + const isHandledByConnection = config.serviceConnections.some(conn => + conn.fromService === serviceName && + Object.keys(conn.variables).includes(key) + ); + + if (!isHandledByConnection) { + // Regular environment variable + service.environment.push({ + key, + value: value.toString() + }); + } + } + + // Then add service connection variables with provider-specific syntax + for (const connection of config.serviceConnections) { + if (connection.fromService === serviceName) { + for (const [varName, varInfo] of Object.entries(connection.variables)) { + // Check if target is a managed service + if (managedServiceMap.has(connection.toService)) { + const targetName = managedServiceMap.get(connection.toService); + + // Use provider-specific reference syntax + service.environment.push({ + key: varName, + // Example: ${resources.MANAGED_SERVICE_NAME.CONNECTION_STRING} + value: `\${resources.${targetName}.${connection.property || 'connectionString'}}` + }); + } else { + // Regular service connection + service.environment.push({ + key: varName, + // Example: ${services.SERVICE_NAME.HOST_PORT} + value: `\${services.${connection.toService}.${connection.property || 'hostport'}}` + }); + } + } + } + } + } else { + // No service connections, just add all environment variables + service.environment = Object.entries(serviceConfig.environment).map(([key, value]) => ({ + key, + value: value.toString() + })); + } + + // Add service to collection + services.push(service); + } + + // Create main configuration + const mainConfig = { + version: '1.0', + provider: 'new-provider', + region: defaultParserConfig.region, + services + }; + + // Create resources configuration if we have managed services + const resourcesConfig = managedServices.length > 0 ? { + version: '1.0', + managedResources: managedServices + } : {}; + + // Return file mappings - the main file is required + const result: { [path: string]: FileOutput } = { + 'awesome-iac.yaml': { + content: this.formatFileContent(mainConfig, TemplateFormat.yaml), + format: TemplateFormat.yaml, + isMain: true + } + }; + + // Add resources file if we have managed services + if (managedServices.length > 0) { + result['templates/resources.yaml'] = { + content: this.formatFileContent(resourcesConfig, TemplateFormat.yaml), + format: TemplateFormat.yaml + }; + } + + return result; + } + + getInfo(): ParserInfo { + return { + providerWebsite: "https://newprovider.example.com", + providerName: "New Provider Cloud", + providerNameAbbreviation: "NP", + languageOfficialDocs: "https://docs.newprovider.example.com/iac", + languageAbbreviation: "NP", + languageName: "New Provider IaC", + defaultParserConfig + }; + } +} + +export default new NewProviderParser(); +``` + +## Configuration and Provider-Specific Logic + +### Service Type Detection + +Create a file for service type configuration in `src/config/newprovider/service-types.ts`: + +```typescript +interface NewProviderServiceTypeConfig { + type: string; + description: string; + versions: string; + isManaged?: boolean; +} + +interface NewProviderServiceTypesConfig { + serviceTypes: { + [key: string]: NewProviderServiceTypeConfig; + }; +} + +export const newProviderServiceTypesConfig: NewProviderServiceTypesConfig = { + serviceTypes: { + 'docker.io/library/mariadb': { + type: 'database', + description: 'MariaDB database service', + versions: '*' + }, + 'docker.io/library/postgres': { + type: 'database', + description: 'PostgreSQL database', + versions: '*', + isManaged: true + }, + 'docker.io/library/redis': { + type: 'cache', + description: 'Redis cache', + versions: '*', + isManaged: true + } + } +}; + +export function getNewProviderServiceType(imageString: string): string { + const baseImage = imageString.split(':')[0]; + return newProviderServiceTypesConfig.serviceTypes[baseImage]?.type || 'web'; +} + +export function isNewProviderManagedService(imageString: string): boolean { + const baseImage = imageString.split(':')[0]; + return !!newProviderServiceTypesConfig.serviceTypes[baseImage]?.isManaged; +} + +export type { NewProviderServiceTypeConfig, NewProviderServiceTypesConfig }; +``` + +### Service Connection Properties + +Update the service connection properties in `src/config/connection-properties.ts`: + +```typescript +export const servicePropertyMappings: Record = { + 'host': { + render: 'host', + digitalOcean: 'PRIVATE_DOMAIN', + newProvider: 'HOST' // Add your provider mapping + }, + 'port': { + render: 'port', + digitalOcean: 'PRIVATE_PORT', + newProvider: 'PORT' // Add your provider mapping + }, + 'hostport': { + render: 'hostport', + digitalOcean: 'PRIVATE_URL', + newProvider: 'ENDPOINT' // Add your provider mapping + } +}; + +export const databasePropertyMappings: Record = { + 'connectionString': { + render: 'connectionString', + digitalOcean: 'DATABASE_URL', + newProvider: 'CONNECTION_STRING' // Add your provider mapping + }, + // Add other mappings... +}; +``` + +## Adding Your Parser to the System + +Update `src/index.ts` to include your new parser: + +```typescript +// Import your new parser +import newProviderParserInstance from './parsers/new-provider'; + +// Add it to the parsers array +const parsers: BaseParser[] = [ + cloudFormationParserInstance, + renderParserInstance, + digitalOceanParserInstance, + newProviderParserInstance // Add your parser here +]; +``` + +## Testing + +Please read our guidelines for testing parsers in the [Testing section](/docs/docker-to-iac/testing). + +## New parser documentation + +Please update documentation in the [github.com/deploystackio/documentation](https://github.com/deploystackio/documentation) repository. + +## Checklist + +1. Support both input types: + - Docker run commands + - Docker Compose files + +2. Handle all service types: + - Regular web/application services + - Managed database services + - Cache services + +3. Handle resource mappings consistently: + - Container ports + - Environment variables + - Volume mounts + - Resource limits + - Service connections + +4. Process service connections correctly: + - Service-to-service references + - Service-to-managed-service references + - Use provider-specific connection syntax + +5. Provide clear error messages for: + - Unsupported features + - Invalid configurations + - Missing required fields + +6. Test edge cases: + - Multiple services with interdependencies + - Complex configurations with service connections + - Various image formats and service types diff --git a/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/index.mdx b/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/index.mdx new file mode 100644 index 0000000..09c73a0 --- /dev/null +++ b/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/index.mdx @@ -0,0 +1,50 @@ +--- +title: Docker to Infrastructure 2 +description: Introduction to the node module docker-to-iac which allows you to transfer docker-compose into IaC templates +sidebar: docker-to-iac +--- + +# Docker to Infrastructure as Code Module + +Docker to IaC is a Node.js module that translates the `docker-compose.yml` file into various types of Infrastructure as Code (IaC) templates. The goal of the module is to make GitHub repositories with docker-compose more easily accessible to various cloud providers such as Amazon Web Services (AWS), Google Cloud, DigitalOcean, and so on. + +- GitHub repository: [github.com/deploystackio/docker-to-iac](https://github.com/deploystackio/docker-to-iac) +- npm registry: [npmjs.com/package/@deploystack/docker-to-iac](https://www.npmjs.com/package/@deploystack/docker-to-iac) + +## Motivation + +The project's motivation comes from the fact that there are so many cloud providers on the free market that it is impossible to know all of them. + +How the project came about: you found an open source project that you want to deploy to your cloud provider, you found the `docker-compose.yml` file, and now you have to extract all the variables by hand or write the Infrastructure as Code template yourself because your company IT policy at work does not allow deployments without IaC. 😀 + +That's how it can work! That's why we want to simplify deployments and minimize vendor lock-in. + +The focus of this project, however, is on container applications with `docker-compose.yml` or applications that can be containerized. + +## Highlights + +- List of all available parsers from module +- Support for docker-compose multiple services +- Setup for default settings for each cloud provider (i.e. CPU, RAM) +- Docker Compose services variables supported: + - image, command, port, environment + +## How does it work? + +The principle of the translation is straightforward. You need a `docker-compose.yml` file and the desired cloud provider where you want to deploy your container. The docker-to-iac module translates `docker-compose.yml` into an IaC or one-click deploy template. + +After the successful translation, you can deploy your containers to your cloud provider. + +## Limitations + +- Only pre-build container possible + +Please read more at the [limitations page](/docs/docker-to-iac/limitations.md) + +## Help wanted + +We would be very happy if you could help us to extend the docker-to-iac module to include additional cloud providers (parsers). All open source repositories listed on our [deploystack.io](https://deploystack.io) website would benefit from this. + +If the docker-to-iac module is extended with another parser, our backend automatically creates an update for the repository [github.com/deploystackio/deploy-templates](https://github.com/deploystackio/deploy-templates). Baiscally: if you add a new parser for the provider "foo-cloud" that has its own IaC language, or one-click deployment supported, all open source projects listed on deploystack.io will be extended with the IaC template for cloud provider "foo-cloud". + +Thank you! diff --git a/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/limitations.mdx b/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/limitations.mdx new file mode 100644 index 0000000..8ba65ba --- /dev/null +++ b/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/limitations.mdx @@ -0,0 +1,89 @@ +--- +title: Limitations +description: Current limitations and constraints of the docker-to-iac module +--- + +# Limitations for docker-to-iac module + +## Registry Support + +The module currently supports Docker images from -> please check [Supported Registries for docker-to-iac module](/docs/docker-to-iac/supported-registries.md) + +## Docker Image Requirement + +The `docker-to-iac` module is designed to work exclusively with pre-built Docker images. This means that each service in your `docker-compose.yml` file must specify an `image` property. + +## Volume Support + +When working with volume mappings in your Docker configuration, be aware that volume support varies among cloud providers: + +- Some providers fully support multiple volume mappings +- Some providers only support the first volume mapping defined in your configuration +- Some providers support ephemeral files only, meaning no persistent volume storage is available +- Volume mapping implementation details can differ between providers + +Please check the specific provider's documentation to understand their volume mapping capabilities and limitations before deployment. + +For example, if your Docker configuration includes multiple volumes: + +```yaml +services: + app: + image: nginx:latest + volumes: + - ./config:/etc/nginx/conf.d + - ./logs:/var/log/nginx + - ./data:/usr/share/nginx/html +``` + +Depending on your chosen provider: + +- All volume mappings might be supported +- Only the first volume mapping (`./config:/etc/nginx/conf.d`) might be implemented +- No volumes might be supported, with only ephemeral storage available + +We recommend reviewing your target provider's documentation for detailed information about their volume support capabilities. + +### Build Instructions Not Supported + +The module does not support services that use the `build` directive. For example: + +```yaml [docker-compose.yml] +# ❌ Not Supported +services: + app: + build: + context: ./build/app + dockerfile: Dockerfile +``` + +Instead, you must use pre-built images: + +```yaml [docker-compose.yml] +# ✅ Supported +services: + app: + image: nginx:latest +``` + +#### Rationale + +This limitation exists because Infrastructure as Code (IaC) templates require specific, immutable container images to ensure consistent deployments. The infrastructure and the selection of cloud providers for this docker-to-iac module only allow pre-build container images. It is technically not possible to create a build with the preconfigured infrastructure. This is why the pre-build check was built in. This happens also because the scope of this module is only pre-build container. + +### Workaround + +If you need to use custom Docker images: + +Build your Docker images locally or in your CI/CD pipeline +Push them to a container registry (like Docker Hub, GitHub Container Registry, or AWS ECR) +Reference the pushed image in your docker-compose file using the image property + +For example: + +```yaml +services: + app: + image: ghcr.io/your-org/your-app:1.0.0 +``` + +This ensures that your IaC templates will have access to the exact same container image across all deployments. diff --git a/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/multi-services-support.mdx b/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/multi-services-support.mdx new file mode 100644 index 0000000..9645e4e --- /dev/null +++ b/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/multi-services-support.mdx @@ -0,0 +1,78 @@ +--- +title: Multi-Service Support +description: Learn about multi-service deployment support - See how docker-to-iac handles multiple services in your container configurations. +--- + +# Multi-Service Support + +Multi-service support refers to the ability of a [parser](/docs/docker-to-iac/parser-explanation) to handle multiple container configurations when translating to Infrastructure as Code (IaC) templates. + +## Docker Run vs Docker Compose + +### Docker Run Commands + +By nature, Docker run commands define a single container. When you have multiple Docker run commands, each represents a separate service: + +```bash +# Service 1 +docker run -d -p 8080:80 nginx:alpine + +# Service 2 +docker run -d -p 6379:6379 redis:latest +``` + +### Docker Compose + +Docker Compose files can define multiple services within a single file: + +```yaml title="docker-compose.yml" +version: '3.2' + +services: + web: + image: nginx:alpine + ports: + - '8080:80' + + cache: + image: redis:latest + ports: + - '6379:6379' +``` + +## Parser Support for Multiple Services + +The ability to deploy multiple services simultaneously varies by cloud provider: + +### Full Multi-Service Support + +Some cloud providers can deploy multiple containers as part of a single deployment. In these cases, docker-to-iac will translate all services to the target IaC template: + +```javascript +// All services will be included in the translation +const translation = translate(dockerComposeContent, { + source: 'compose', + target: 'CFN' // AWS CloudFormation supports multiple services +}); +``` + +### Limited Service Support + +Some providers don't support deploying multiple containers simultaneously. For these providers: + +- For Docker Compose input: Only the first service from the file will be translated +- For Docker run commands: Each command must be translated separately + +```javascript +// Only the first service will be translated +const translation = translate(dockerComposeContent, { + source: 'compose', + target: 'RND' // Render.com currently supports single service deployments +}); +``` + +## Provider-Specific Behavior + +Before using a specific parser, check its multi-service capabilities in the [parser documentation](/docs/docker-to-iac/parser-explanation). This helps ensure your deployment strategy aligns with the provider's capabilities. + +Note that some providers may have different service limits or deployment patterns even when they support multiple services. Always consult the target provider's documentation for specific limitations. diff --git a/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/parser-explanation.mdx b/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/parser-explanation.mdx new file mode 100644 index 0000000..ca69734 --- /dev/null +++ b/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/parser-explanation.mdx @@ -0,0 +1,61 @@ +--- +title: Parser Explanation +description: Understand how parsers translate Docker run commands and Docker Compose files into cloud-specific Infrastructure as Code templates. Learn about provider configurations and language support. +--- + +# Parser Explanation in docker-to-iac + +A parser in docker-to-iac translates Docker configurations (either Docker run commands or docker-compose.yml files) into Infrastructure as Code (IaC) or One-Click Deploy templates. Each parser is designed to target a specific IaC language or cloud provider template format. + +## Input Types + +docker-to-iac can process two types of input: + +### Docker Run Commands + +```bash +docker run -d -p 8080:80 -e NODE_ENV=production nginx:latest +``` + +### Docker Compose Files + +```yaml +version: '3' +services: + web: + image: nginx:latest + ports: + - "8080:80" + environment: + NODE_ENV: production +``` + +## API + +For detailed API documentation, see the [parser API reference](/docs/docker-to-iac/api). + +## Default Parser Config + +Each parser includes default configurations specific to its target cloud provider. These defaults are necessary because providers have different compute specifications and limitations. + +Example: AWS Fargate has a minimum CPU allocation of 256, while DigitalOcean's [minimum setting is 1 vCPU](https://www.digitalocean.com/pricing/app-platform). The default parser config handles these provider-specific requirements. + +To retrieve default parser configurations through the API, see the [parser info documentation](/docs/docker-to-iac/api#get-parser-info). + +## Parser vs. Language + +The [ParserInfo type](https://github.com/deploystackio/docker-to-iac/blob/main/src/parsers/base-parser.ts) separates variables between `Provider` and `Language`. This separation exists because some cloud providers support multiple IaC languages. + +For example, AWS infrastructure can be defined using: + +- CloudFormation +- AWS CDK (for TypeScript, Python, etc.) +- Terraform + +When adding new parsers, consider whether multiple IaC languages are possible for your target provider. This affects how you name your parser file in `src/parsers/.ts`. It's why the [`translate()`](/docs/docker-to-iac/api#translate-api) method requires the target IaC language name (e.g., `CFN`) rather than the provider name (e.g., `AWS`). + +## Parser Implementation Notes + +Creating parsers for multi-cloud IaC tools like Terraform presents additional challenges. Terraform's [extensive provider ecosystem](https://registry.terraform.io/browse/providers) means a Terraform parser would need complex logic to handle various provider-specific implementations, making maintenance more difficult. + +In contrast, single-provider languages like AWS CloudFormation have a one-to-one relationship with their cloud provider, simplifying parser implementation and maintenance. diff --git a/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/parser/aws-cloudformation.mdx b/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/parser/aws-cloudformation.mdx new file mode 100644 index 0000000..30861bb --- /dev/null +++ b/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/parser/aws-cloudformation.mdx @@ -0,0 +1,97 @@ +--- +title: AWS CloudFormation Parser +description: Translate docker docker-compose.yml file into AWS Cloud Formation with DeployStack +--- + +# AWS CloudFormation - Parser Full Documentation + +The parser for CloudFormation translates the `docker-compose.yml` file into CloudFormation. The parser logic can be found in GitHub inside [docker-to-iac repo](https://github.com/deploystackio/docker-to-iac/blob/main/src/parsers/aws-cloudformation.ts). + +## Parser language abbreviation for API + +- `languageAbbreviation`: `CFN`. + +## Prerequisite to deploy CloudFormation Template + +To deploy the CloudFormation template in your AWS account, you need a VPC with internet access. It should also be possible to create ENI ([AWS Elastic Network Interface](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-eni.html)) with public IP. The template uses __AWS Fargate__ without an Application Load Balancer to save costs. + +If you have the [default VPC](https://docs.aws.amazon.com/vpc/latest/userguide/default-vpc.html) in your AWS account that should be sufficient. + +## Architecture + +The architecture deploys an ECS service into a serverless [AWS Fargate](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/AWS_Fargate.html) cluster. An ECS service = service from `docker-compose.yml`. This means if you have two services in your docker-compose file, you will end up deploying two ECS services into your Fargate cluster. + +![AWS Architecture](../../assets/images/docker-to-iac/aws-fargate.drawio.png) + +The tasks within ECS services create an ENI that has a public IP address. Since we do not use an ALB ([Application Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/introduction.html)), you can only access the tasks via the port and the public IP address. + +When creating CloudFormation template, we decided not to use ALB to save costs. You can of course modify the CloudFormation template and add your ALB if needed. + +## Security Configuration + +### Container Security Groups + +For development and testing purposes, the template configures security groups with open TCP ports (0-65535). This configuration enables easy testing but is not recommended for production use. If you plan to use this template in production, modify the security group rules to restrict access to specific ports. + +```yaml +SecurityGroupIngress: + - IpProtocol: tcp + FromPort: 0 + ToPort: 65535 + CidrIp: 0.0.0.0/0 +``` + +### Container Root Filesystem + +To enable writes to ephemeral ECS storage, containers are configured with: + +```yaml +ReadonlyRootFilesystem: false +``` + +## Default output format + +- The default output format for this parser: `YAML`. + +## File Configuration + +The AWS CloudFormation parser generates a single consolidated template: + +- `aws-cloudformation.cf.yml` - The comprehensive CloudFormation template that defines all resources including ECS clusters, services, tasks, security groups, and IAM roles + +This single-file approach encapsulates the entire infrastructure definition in YAML format, making it ready for immediate deployment through the AWS CloudFormation console, CLI, or other AWS deployment tools. + +## Supported Docker Compose Variables + +The current version supports the following Docker Compose variables: + +For __services__: + +- image +- environment +- ports +- command + + +The supported variables that are not on this list are ignored. This means that they are not translated by the parser in Infrastructure as Code from `docker-compose.yml` or docker run command. + + +## Storage Support + +The current implementation uses ephemeral storage provided by AWS Fargate. Persistent storage solutions like EFS (Elastic File System) or EBS (Elastic Block Store) are not automatically configured due to complexity with multiple mount points and automated deployment requirements. + +For applications requiring persistent storage, consider: + +- Using external storage services (e.g., Amazon RDS for databases) +- Manually configuring EBS volumes +- Implementing a custom storage solution + +## Multi Services Support + +Multi `services` support for CloudFormation: __yes__ + +Please read more about [multi service support here](/docs/docker-to-iac/multi-services-support). + + +This CloudFormation template is designed for development and testing environments. For production deployments, review and adjust security groups, storage configuration, and other security settings according to your requirements. + diff --git a/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/parser/digitalocean.mdx b/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/parser/digitalocean.mdx new file mode 100644 index 0000000..5ea2624 --- /dev/null +++ b/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/parser/digitalocean.mdx @@ -0,0 +1,189 @@ +--- +title: DigitalOcean Parser +description: Translate docker docker-compose.yml file into DigitalOcean Infrastructure as Code with DeployStack +--- + +# DigitalOcean - Parser Full Documentation + +The parser for DigitalOcean translates the `docker-compose.yml` file into a DigitalOcean [App Spec](https://docs.digitalocean.com/products/app-platform/) template. The parser logic can be found in GitHub inside the [docker-to-iac repo](https://github.com/deploystackio/docker-to-iac/blob/main/src/parsers/digitalocean.ts). + +## Parser language abbreviation for API + +- `languageAbbreviation`: `DOP`. + +## Prerequisite to deploy DigitalOcean App Spec + +To use the DigitalOcean App Spec, you need a valid DigitalOcean account with access to the App Platform and sufficient credits. + +## Architecture + +The DigitalOcean App Spec will deploy your application entirely within App Platform using containerized services: + +### App Platform Services + +Services in your App Platform deployment fall into two categories: + +#### HTTP Services + +- Web-facing containers that serve HTTP traffic +- Automatically configured with HTTPS routing: + - First service gets the root path `/` + - Additional services receive paths based on their names, e.g., `/servicename` +- Ideal for web applications, APIs, and frontend services + +#### TCP Services + +- Database containers (MySQL, PostgreSQL, Redis, etc.) run as internal TCP services +- Configured with appropriate health checks and internal ports +- No external HTTP routing - only accessible by other services within the app +- Suitable for databases, caches, and message queues + +### Important Note About Databases + +While DigitalOcean offers managed database services, these cannot be automatically provisioned through one-click deployment. Instead, database containers (like MySQL, PostgreSQL, Redis) are deployed as TCP services within App Platform, allowing: + +- Immediate deployment without pre-existing infrastructure +- Internal communication between application components +- Simplified configuration for development and testing + +For production use cases where you need managed databases, you should: + +1. Manually create managed databases in your DigitalOcean account +2. Update the application configuration to use these managed instances + +After deployment, all services can be monitored and managed through your DigitalOcean App Platform dashboard. + +## Default output format + +- The default output format for this parser: `YAML`. + +## File Configuration + +The DigitalOcean parser generates a structured output with a specific file organization: + +- `.do/deploy.template.yaml` - The main App Platform specification file that defines all services, environment variables, and configuration options for deployment + +This single-file structure follows DigitalOcean's App Platform requirements, where all deployment configurations are contained within the standard location expected by the DigitalOcean CLI and deployment tools. + +## Supported Docker Compose Variables + +This parser supports the following Docker Compose variables for services: + +- image +- environment +- ports +- command + + +Supported variables not listed above will be ignored. They will not be translated into the Infrastructure as Code from `docker-compose.yml` or docker run command. + + +## Database Support + +DigitalOcean App Platform supports running database containers as internal TCP services. The parser automatically configures these services with appropriate health checks and port settings to ensure proper communication within your application. + +### Supported Databases + +The parser recognizes and configures the following database types: + +- MySQL/MariaDB (port 3306) +- PostgreSQL (port 5432) +- Redis (port 6379) +- MongoDB (port 27017) + +### Configuration Details + +Database service configurations are defined in `src/config/digitalocean/database-types.ts`. This configuration maps Docker images to their corresponding TCP port and health check settings. + +To add or modify database configurations: + +1. Locate the `database-types.ts` file +2. Edit the `digitalOceanDatabaseConfig` object +3. Define the mapping using this structure: + +```typescript +'docker.io/library/mariadb': { + engine: 'MYSQL', + description: 'MariaDB database service - maps to MySQL managed database due to compatibility', + portNumber: 3306 +} +``` + +### Example Transformation + +Original docker-compose.yml: + +```yaml +services: + db: + image: mariadb:11.2 + environment: + MYSQL_DATABASE: myapp + app: + image: nginx:alpine + ports: + - "80:80" +``` + +Generated App Spec: + +```yaml +spec: + services: + - name: db + image: + registry_type: DOCKER_HUB + registry: library + repository: mariadb + tag: "11.2" + health_check: + port: 3306 + internal_ports: + - 3306 + - name: app + image: + registry_type: DOCKER_HUB + registry: library + repository: nginx + tag: alpine + http_port: 80 + routes: + - path: / +``` + + +While running databases as App Platform services works well for development and testing, for production workloads consider using DigitalOcean's managed database offerings for better reliability and maintenance. + + +### Understanding TCP Services + +When a database image is detected, the parser: + +1. Configures the service without HTTP routing +2. Sets up appropriate internal ports for database communication +3. Adds health checks on the database's standard port +4. Ensures the service can communicate with other containers in your app + +This approach allows immediate deployment while maintaining proper isolation and communication between your application components. + +## Volume Support + +DigitalOcean App Platform supports ephemeral files only. This means: + +- No persistent volume storage is available +- Local filesystem is limited to 2GB +- Files are temporary and will be deleted after deployments or container replacements +- Each container instance has its own separate filesystem +- Changes to the filesystem are lost when instances are scaled or redeployed + + +Any `volumes` directives in your docker-compose.yml or docker run command will be ignored during the translation to App Platform specifications. + + +## Multi Services Support + +Multi `services` support for DigitalOcean: __yes__ + +DigitalOcean supports multiple services in a single App Spec file. + +Please read more about [multi service support here](/docs/docker-to-iac/multi-services-support). diff --git a/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/parser/helm.mdx b/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/parser/helm.mdx new file mode 100644 index 0000000..b99c6ea --- /dev/null +++ b/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/parser/helm.mdx @@ -0,0 +1,210 @@ +--- +title: Helm Parser Documentation +description: Translate Docker Compose files into Kubernetes Helm Charts with DeployStack docker-to-iac module +--- + +# Helm - Parser Full Documentation + +The parser for Helm translates Docker configurations into Kubernetes Helm Charts. The parser logic can be found in GitHub inside the [docker-to-iac repo](https://github.com/deploystackio/docker-to-iac/blob/main/src/parsers/helm.ts). + +## Parser language abbreviation for API + +- `languageAbbreviation`: `HELM`. + +## Prerequisite to deploy Helm Charts + +To deploy the generated Helm Charts, you need: + +- A Kubernetes cluster (local or cloud-based) +- Helm CLI installed (version 3.x recommended) +- Appropriate RBAC permissions to deploy resources in your target namespace + +### Kubernetes Resources + +The generated Helm Chart creates the following Kubernetes resources for each service in your Docker configuration: + +- **Deployments**: Container specifications, replica count, resource limits +- **Services**: Network access to your pods with appropriate ports +- **ConfigMaps**: Non-sensitive environment variables +- **Secrets**: Sensitive environment variables (passwords, tokens, etc.) + +### Database Support + +For database services, the parser leverages Helm's dependency management to incorporate official Bitnami charts: + +- **MySQL/MariaDB**: Uses Bitnami's MySQL/MariaDB chart +- **PostgreSQL**: Uses Bitnami's PostgreSQL chart +- **Redis**: Uses Bitnami's Redis chart +- **MongoDB**: Uses Bitnami's MongoDB chart + +Each database dependency is configured with appropriate defaults and includes persistent storage for data. + +## Default output format + +- The default output format for this parser: `YAML`. + +## File Configuration + +The Helm parser generates a complete Helm Chart directory structure: + +- `Chart.yaml` - The main chart definition with metadata and dependencies +- `values.yaml` - Configuration values that can be customized at deployment time +- `templates/` - Directory containing Kubernetes YAML templates: + - `deployment.yaml` - Deployment specifications for each service + - `service.yaml` - Service definitions for network access + - `configmap.yaml` - ConfigMap for non-sensitive environment variables + - `secret.yaml` - Secret for sensitive environment variables + - `_helpers.tpl` - Helper functions for template generation + - `NOTES.txt` - Usage instructions displayed after installation + +This multi-file approach follows the standard Helm Chart structure and allows for maximum flexibility when deploying to Kubernetes. + +## Supported Docker Compose Variables + +This parser supports the following Docker Compose variables: + +- `image` +- `environment` +- `ports` +- `command` +- `volumes` + + +The parser automatically detects sensitive environment variables (containing keywords like "password", "secret", "key", "token", or "auth") and places them in Kubernetes Secrets instead of ConfigMaps. + + +## Volume Support + +The parser supports Docker volume mappings by converting them to Kubernetes volume mounts: + +- Each volume is converted to a hostPath volume by default +- Volume names are sanitized to conform to Kubernetes naming conventions +- For production use, you should modify the generated templates to use more appropriate volume types (PersistentVolumeClaims, etc.) + +## Database Integration + +When a database service is detected (MySQL, PostgreSQL, Redis, MongoDB), the parser: + +1. Adds the corresponding Bitnami Helm chart as a dependency in `Chart.yaml` +2. Configures database settings in `values.yaml` +3. Maps environment variables to the expected format for the database chart +4. Sets up appropriate persistence configurations + +### Example Database Configuration + +For a PostgreSQL database in your Docker Compose file: + +```yaml +services: + db: + image: postgres:13 + environment: + POSTGRES_USER: myuser + POSTGRES_PASSWORD: mypassword + POSTGRES_DB: myapp +``` + +The parser will create: + +```yaml +# In Chart.yaml +dependencies: + - name: db + repository: https://charts.bitnami.com/bitnami + version: ^12.0.0 + condition: dependencies.db.enabled + +# In values.yaml +dependencies: + db: + enabled: true + auth: + postgres: + password: mypassword + database: myapp + username: myuser + password: mypassword + primary: + service: + ports: + postgresql: 5432 + persistence: + enabled: true + size: 8Gi +``` + +## Service Connections + +The parser supports service-to-service connections by leveraging Kubernetes DNS for service discovery. When a service refers to another service in an environment variable, the parser automatically configures the appropriate DNS references. + +For example, if your `app` service connects to a `db` service: + +```yaml +# Docker Compose +services: + app: + image: myapp + environment: + DATABASE_URL: postgresql://postgres:password@db:5432/mydb + + db: + image: postgres + environment: + POSTGRES_PASSWORD: password + POSTGRES_DB: mydb +``` + +The parser will create: + +```yaml +# In ConfigMap template +data: + DATABASE_URL: {{ include "deploystack.serviceReference" (dict "service" (index $.Values.services "db") "serviceKey" "db") }} +``` + +Which resolves to the Kubernetes DNS name: `db.{{ .Release.Namespace }}.svc.cluster.local:5432` + +## Multi Services Support + +Multi `services` support for Helm: **yes** + +Helm Charts are designed to handle multiple services and dependencies in a single deployment, making them ideal for complex applications. The parser transforms all services from your Docker Compose file into corresponding Kubernetes resources. + +Please read more about [multi service support here](/docs/docker-to-iac/multi-services-support). + +## Deployment Instructions + +To deploy the generated Helm Chart: + +1. Navigate to the directory containing the generated chart +2. Install dependencies: + + ```bash + helm dependency update + ``` + +3. Install the chart: + + ```bash + helm install my-release . + ``` + +4. For custom configurations: + + ```bash + helm install my-release . --set services.app.replicaCount=2 + ``` + +## Production Considerations + +For production deployments, consider the following modifications to the generated chart: + +1. Replace hostPath volumes with appropriate persistent volume claims +2. Adjust resource limits in `values.yaml` +3. Configure proper ingress settings for external access +4. Enable and configure horizontal pod autoscaling +5. Set up proper liveness and readiness probes + + +The generated Helm Chart is a starting point that you should review and customize to match your production requirements and security best practices. + diff --git a/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/parser/index.mdx b/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/parser/index.mdx new file mode 100644 index 0000000..87c45ce --- /dev/null +++ b/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/parser/index.mdx @@ -0,0 +1,14 @@ +--- +title: Available parsers +description: View all available parsers in docker-to-iac for converting Docker Compose to cloud infrastructure templates. Supports major cloud providers. +menuTitle: Available parser +--- + +# Available parser list for module docker-to-iac + +Here you can find the list of available [parsers](/docs/docker-to-iac/parser-explanation.md): + +- [AWS CloudFormation](/docs/docker-to-iac/parser/aws-cloudformation.md) +- [Render.com](/docs/docker-to-iac/parser/render.com.md) +- [DigitalOcean](/docs/docker-to-iac/parser/digitalocean.md) +- [Helm (Kubernetes)](/docs/docker-to-iac/parser/helm.md) diff --git a/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/parser/render.com.mdx b/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/parser/render.com.mdx new file mode 100644 index 0000000..926c2fe --- /dev/null +++ b/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/parser/render.com.mdx @@ -0,0 +1,133 @@ +--- +title: Render.com - Parser Full Documentation +description: Translate docker docker-compose.yml file into Render.com Infrastructure as Code with DeployStack +--- + +# Render.com - Parser Full Documentation + +The parser for Render.com translates the `docker-compose.yml` file into Render [BluePrint](https://render.com/docs/infrastructure-as-code). The parser logic can be found in GitHub inside [docker-to-iac repo](https://github.com/deploystackio/docker-to-iac/blob/main/src/parsers/render.ts). + +## Parser language abbreviation for API + +- `languageAbbreviation`: `RND`. + +## Prerequisite to deploy Render BluePrint + +There are no special requirements for using the Render.com blueprint. However, you need a valid render.com account with sufficient credits. + +## Architecture + +The BluePrint will create a render "web" service. + +Type = "[Web Service](https://render.com/docs/blueprint-spec#type)". + +Render dashboard will list all your web services. At the top, you can switch between Dashboard and BluePrints. + +![Render BluePrints](../../assets/images/docker-to-iac/render.com-dashboard-blueprints.png) + +After the BluePrint has been created through one-click deployment, the BluePrint will be visible in the BluePrint menu. + +In contrast to other cloud providers, Render.com's usability is very trivial. There is no VPC / VNet or anything else. After successful deployment, you can open your service via a URL. + +## Default output format + +- The default output format for this parser: `YAML`. + +## File Configuration + +The Render.com parser generates a single file output: + +- `render.yaml` - The main Blueprint configuration file that defines all services, environment variables, and disk configurations + +This straightforward single-file approach aligns with Render's Blueprint specification, which requires all service definitions to be contained within a single YAML file. The file is structured according to Render's requirements with services, environment variables, and disk configurations properly organized for immediate deployment. + +## Supported Docker Compose Variables + +The current version supports the following Docker Compose variables: + +For __services__: + +- image +- environment +- ports +- command + + +The supported variables that are not on this list are ignored. This means that they are not translated by the parser in Infrastructure as Code from `docker-compose.yml` or docker run command. + + +## Volume Support + +Render.com offers two types of storage options: + +### Default: Ephemeral Filesystem + +By default, Render services use an ephemeral filesystem where: + +- Changes to the filesystem are lost after deployments or restarts +- Each service instance has its own separate filesystem +- No data persists between deployments + +### Persistent Disk Option + +The parser supports adding persistent disk storage through the `volumes` directive: + +- Persistent disks are automatically configured with 10GB size +- Only one disk per service is supported +- Files are preserved across deployments and restarts +- Only filesystem changes under the disk's mount path are preserved + +Important limitations for persistent disks: + +- A disk can only be accessed by a single service instance +- Services with persistent disks cannot scale to multiple instances + +Read more here: [render.com/docs/disks](https://render.com/docs/disks) + +## Service Types + +The parser automatically determines the appropriate service type for each container in your Docker configuration: + +### Web Services (Default) + +By default, services are created as `type: web`, which is suitable for: + +- HTTP-based applications +- Frontend applications +- API servers +- Any service that needs to be publicly accessible + +### Private Services + +For databases and other TCP-based services, the parser automatically sets `type: pserv`. These services: + +- Are not publicly accessible +- Can communicate with other services over TCP +- Are ideal for databases and backend services + +Read more here: [render.com/docs/private-services](https://render.com/docs/private-services). + +The service type is determined based on the Docker image being used. For example: + +```yaml +services: + web: + image: nginx:latest + # Automatically set to type: web + + db: + image: mariadb:11.2 + # Automatically set to type: pserv +``` + +### Adding New Service Types + +If you're using a service that should be private but isn't automatically detected, please visit our [Render: Contributing to Render Service Types docs page](/docs/docker-to-iac/render-contributing-to-service-types). + +## Multi Services Support + +Multi `services` support for Render.com: __yes__ + +Since [multi services](https://render.com/docs/blueprint-spec#root-level-fields) feature is supported. + +Please read more about [multi service support here](/docs/docker-to-iac/multi-services-support). diff --git a/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/project-structure.mdx b/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/project-structure.mdx new file mode 100644 index 0000000..1c4126c --- /dev/null +++ b/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/project-structure.mdx @@ -0,0 +1,175 @@ +--- +title: Project Structure +description: Directory structure and organization of the docker-to-iac module, including guidance for adding new parsers, source handlers, and tests. +--- + +# Project Structure of docker-to-iac Module + +The project follows standard npm module organization with a well-defined structure to handle both Docker run commands and Docker Compose files, supporting multiple output formats and comprehensive testing. + +## Directory Structure + +```bash +docker-to-iac/ +|-- src/ # Source code +| |-- index.ts # Main entry point +| |-- config/ # Provider-specific configurations +| | |-- connection-properties.ts +| | |-- digitalocean/ +| | | |-- database-types.ts +| | |-- render/ +| | |-- service-types.ts +| |-- parsers/ # IaC parsers for different cloud providers +| | |-- aws-cloudformation.ts +| | |-- base-parser.ts +| | |-- digitalocean.ts +| | |-- render.ts +| |-- sources/ # Input source handlers +| | |-- base.ts +| | |-- factory.ts +| | |-- compose/ # Docker Compose handling +| | | |-- index.ts +| | | |-- validate.ts +| | |-- run/ # Docker run command handling +| | |-- index.ts +| |-- types/ # TypeScript type definitions +| | |-- container-config.ts +| | |-- environment-config.ts +| | |-- service-connections.ts +| |-- utils/ # Helper utilities +| |-- constructImageString.ts +| |-- detectDatabaseEnvVars.ts +| |-- digitalOceanParserServiceName.ts +| |-- getDigitalOceanDatabaseType.ts +| |-- getImageUrl.ts +| |-- parseCommand.ts +| |-- parseDockerImage.ts +| |-- parseEnvFile.ts +| |-- processEnvironmentVariablesGeneration.ts +| |-- resolveEnvironmentValue.ts +| |-- (... and many more) +|-- test/ # Test files +| |-- e2e/ # End-to-end tests +| | |-- assertions/ # Test assertions +| | | |-- digitalocean.ts +| | | |-- do-port-assertions.ts +| | | |-- port-assertions.ts +| | | |-- render.ts +| | |-- docker-compose-files/ # Test Docker Compose files +| | |-- docker-run-files/ # Test Docker run commands +| | |-- output/ # Test output directory +| | |-- utils/ # Test utilities +| | |-- index.ts # Main E2E test executor +| | |-- test1.ts # Environment variables and volume mapping tests +| | |-- test2.ts # Port mapping tests +| | |-- test3.ts # Environment variable substitution tests +| | |-- test4.ts # Schema validation tests +| |-- unit/ # Unit tests +| | |-- config/ # Configuration tests +| | |-- parsers/ # Parser tests +| | |-- sources/ # Source handler tests +| | |-- utils/ # Utility function tests +| |-- test.ts # Main test entry point +|-- eslint.config.mjs # ESLint configuration +|-- tsconfig.json # TypeScript configuration +|-- vitest.config.ts # Vitest configuration +|-- package.json # Package configuration +|-- README.md # Project documentation +``` + +## Directory Purposes + +### Core Directories + +- `src/` - Source code for the module +- `test/` - Test files organized by test type (unit and end-to-end) +- `dist/` - Compiled output (generated during build) + +### Source Code Organization + +#### Config (`src/config/`) + +Contains provider-specific configurations: + +- `connection-properties.ts` - Cross-provider connection property mappings +- `digitalocean/` - DigitalOcean App Platform specific configurations + - `database-types.ts` - Database type mappings for DigitalOcean +- `render/` - Render.com specific configurations + - `service-types.ts` - Service type mappings for Render deployments + +#### Parsers (`src/parsers/`) + +Contains IaC-specific parsers for different cloud providers: + +- `base-parser.ts` - Base parser class that defines common functionality +- `aws-cloudformation.ts` - AWS CloudFormation parser +- `digitalocean.ts` - DigitalOcean App Platform parser +- `render.ts` - Render Blueprint parser +- ... additional parsers for other providers + +#### Source Handlers (`src/sources/`) + +Handles different input types: + +- `base.ts` - Base source handler interface +- `factory.ts` - Factory for creating appropriate source handlers +- `compose/` - Docker Compose file processing + - `index.ts` - Main Compose parser + - `validate.ts` - Compose file validation +- `run/` - Docker run command processing + - `index.ts` - Docker run command parser + +#### Types (`src/types/`) + +TypeScript type definitions: + +- `container-config.ts` - Container and service configuration types +- `environment-config.ts` - Environment variable configuration types +- `service-connections.ts` - Service connection configuration types + +#### Utilities (`src/utils/`) + +Helper functions for parsing and processing: + +- `constructImageString.ts` - Docker image string construction +- `detectDatabaseEnvVars.ts` - Database environment variable detection +- `digitalOceanParserServiceName.ts` - Name formatting for DigitalOcean +- `getDigitalOceanDatabaseType.ts` - Database type detection for DigitalOcean +- `parseDockerImage.ts` - Docker image parsing +- `parseEnvFile.ts` - Environment file parsing +- `resolveEnvironmentValue.ts` - Environment variable resolution +- And many more utility functions for specific operations + +### Test Organization + +#### End-to-End Tests (`test/e2e/`) + +Integration tests that validate the complete workflow: + +- `assertions/` - Validation functions for test output +- `docker-compose-files/` - Test Docker Compose files +- `docker-run-files/` - Test Docker run commands +- `output/` - Generated test outputs +- `utils/` - Test helper utilities +- `test1.ts` through `test4.ts` - Specific test scenarios: + 1. Environment variables and volume mapping + 2. Port mappings + 3. Environment variable substitution + 4. Schema validation + +#### Unit Tests (`test/unit/`) + +Tests for individual components: + +- `config/` - Tests for configuration modules +- `parsers/` - Tests for IaC parsers +- `sources/` - Tests for source handlers +- `utils/` - Tests for utility functions + +## Adding New Parser + +Please check our [Adding a New Parser](/docs/docker-to-iac/example-of-a-new-parser) documentation for detailed instructions on how to add a new parser to the project. This includes creating a new parser file, implementing the parsing logic, and ensuring compatibility with existing configurations. + +### Adding New Tests + +Please refer to the [Testing](/docs/docker-to-iac/testing) documentation for guidelines on adding new tests, including unit and end-to-end tests. diff --git a/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/quickstart.mdx b/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/quickstart.mdx new file mode 100644 index 0000000..67009de --- /dev/null +++ b/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/quickstart.mdx @@ -0,0 +1,64 @@ +--- +title: Quickstart Guide +description: Quickstart guide for using docker-to-iac to translate Docker run commands and Docker Compose files into infrastructure as code templates +--- + +# Quickstart Guide + +## Installation + +First, install the module and its dependencies: + +```bash +npm i @deploystack/docker-to-iac +``` + +## Usage Examples + +### Translating Docker Compose + +```javascript +import { translate } from '@deploystack/docker-to-iac'; +import { readFileSync, writeFileSync } from 'fs'; + +// Read Docker Compose file content +const dockerComposeContent = readFileSync('path/to/docker-compose.yml', 'utf8'); + +const translatedConfig = translate(dockerComposeContent, { + source: 'compose', + target: 'CFN', + templateFormat: 'yaml' +}); + +// Write the translated config to a file +writeFileSync('output-aws.yml', translatedConfig); +``` + +### Translating Docker Run Commands + +```javascript +import { translate } from '@deploystack/docker-to-iac'; +import { writeFileSync } from 'fs'; + +// Your docker run command +const dockerRunCommand = 'docker run -d -p 8080:80 -e NODE_ENV=production nginx:latest'; + +const translatedConfig = translate(dockerRunCommand, { + source: 'run', + target: 'CFN', + templateFormat: 'yaml' +}); + +// Write the translated config to a file +writeFileSync('output-aws.yml', translatedConfig); +``` + +### Translation Options + +When using the `translate` function, you can specify: + +- `source`: Either 'compose' or 'run' depending on your input +- `target`: The IaC language to translate to (e.g., 'CFN' for AWS CloudFormation) +- `templateFormat`: Output format - 'json', 'yaml', or 'text' + +For a complete list of supported parsers and formats, visit the [API documentation](/docs/docker-to-iac/api). diff --git a/docs-backup-2025-06-18T14-33-44-828Z/docs/index.mdx b/docs-backup-2025-06-18T14-33-44-828Z/docs/index.mdx new file mode 100644 index 0000000..f89e880 --- /dev/null +++ b/docs-backup-2025-06-18T14-33-44-828Z/docs/index.mdx @@ -0,0 +1,83 @@ +--- +title: DeployStack Documentation +description: Welcome to DeployStack documentation. Learn how to automate Docker Compose deployments across cloud providers with Infrastructure as Code templates and one-click deployments. +icon: CircleHelp +--- + +import { CloudUpload, Terminal, FileText, Container, BookOpenText, MessageCircleHeart } from 'lucide-react'; + +# DeployStack Documentation + +DeployStack converts your **Docker configurations** into **Infrastructure as Code** (IaC) templates for multiple cloud providers. Whether you have a docker-compose.yml file or docker run commands, it generates the necessary AWS CloudFormation, Render.com Blueprint, DigitalOcean specifications, or Kubernetes Helm charts for example. This lets you and your users deploy the same application consistently across different cloud platforms using their native deployment mechanisms, **without needing to manually create** each provider's infrastructure. + +## Get Started + +DeployStack simplifies cloud deployment through three key steps: configure your Docker setup, translate docker compose or run command to IaC templates, and enable one-click deployment for your users. Start by understanding the core concepts and how to integrate DeployStack with your repository. + +### Core Concepts + + +} title="Quickstart" href="/docs/deploystack/getting-started"> +Start with our Getting Started Guide to understand the basics of DeployStack. + +} title="One-Click Deploy" href="/docs/deploystack/one-click-deploy"> +Learn how to enable One-Click Deploy buttons for your repository. + +} title="Configuration" href="/docs/deploystack/deploystack-configuration-directory"> +Configuration file placed to your repository, telling Zerops how to build and start your app. + + + +### Supported Cloud Providers + +DeployStack generates infrastructure templates for major cloud providers, each optimized for their specific deployment patterns. AWS CloudFormation templates use Fargate for containerized workloads, DigitalOcean leverages App Platform, and Render.com implements Blueprints for smooth deployment. While translating your docker command to Infrastructure as Code by using [docker-to-iac](/docs/docker-to-iac/index.md) module, you can choose your target provider. + + + +AWS + + +DigitalOcean + + +Render.com + + +Helm + + + +### DeployStack Ecosystem + +DeployStack consists of several integrated components that work together to enable consistent Docker to cloud deployment. Each repository serves a specific purpose in the ecosystem: + + +} title="docker-to-iac" href="https://github.com/deploystackio/docker-to-iac"> +The core Node.js module that handles Docker configuration translation to Infrastructure as Code templates + +} title="documentation" href="https://github.com/deploystackio/documentation"> +Central repository for all DeployStack documentation and guides + +} title="deploy-templates" href="https://github.com/deploystackio/deploy-templates"> +Houses all generated Infrastructure as Code templates for supported repositories + +} title="feedback" href="https://github.com/deploystackio/feedback"> +Public repository for feature requests, bug reports, and roadmap discussions + + + +## Contributing to DeployStack docker-to-iac module + +DeployStack is open source and we welcome contributions. Here's how you can help: + +- Add support for new cloud providers +- Improve existing Infrastructure as Code templates +- Enhance documentation +- Report issues and suggest improvements + +Visit our [GitHub repository](https://github.com/deploystackio/docker-to-iac) to get started. + +## Community and Support + +- Join our [Discord community](https://discord.gg/UjFWwByB) +- Check our [troubleshooting guide](/docs/deploystack/troubleshooting.md) diff --git a/docs/deploystack/application-logo-configuration.mdx b/docs/deploystack/application-logo-configuration.mdx index 5535809..92a3349 100644 --- a/docs/deploystack/application-logo-configuration.mdx +++ b/docs/deploystack/application-logo-configuration.mdx @@ -9,7 +9,7 @@ Add a custom logo to make your application stand out in the DeployStack catalog. ## Adding Your Logo -Configure your logo in `.deploystack/config.yml` - [DeployStack Configuration File Reference](/docs/deploystack/deploystack-config-file): +Configure your logo in `.deploystack/config.yml` - [DeployStack Configuration File Reference](/deploystack/deploystack-config-file): ```yaml application: diff --git a/docs/deploystack/deploystack-config-file.mdx b/docs/deploystack/deploystack-config-file.mdx index 78d2686..a5dfc95 100644 --- a/docs/deploystack/deploystack-config-file.mdx +++ b/docs/deploystack/deploystack-config-file.mdx @@ -56,7 +56,7 @@ The override process follows this order: ### Branch Deployment Settings -Before configuring multiple branch deployments, ensure you have installed the [DeployStack Repository Sync GitHub App](/docs/deploystack/github-application), as it's required for branch monitoring and template updates. +Before configuring multiple branch deployments, ensure you have installed the [DeployStack Repository Sync GitHub App](/deploystack/github-application), as it's required for branch monitoring and template updates. You can configure multiple branch deployments using the `deployment.branches` section: @@ -109,7 +109,7 @@ This is especially useful for projects that maintain multiple active versions si The optional `exclude_providers` array allows you to specify which cloud providers should be excluded from template generation for particular branches. This is useful when certain features in a branch version may not be compatible with specific cloud providers. Valid provider codes are: -Please check our [current supported provider list here](/docs/docker-to-iac/parser/index). +Please check our [current supported provider list here](/docker-to-iac/parser/index). For example, if your beta version uses features only supported in DigitalOcean, you might exclude the other providers: @@ -256,4 +256,4 @@ deployment: ### Minimal Configuration example for logo update -Please visit our [Application Logo Configuration](/docs/deploystack/application-logo-configuration) page. +Please visit our [Application Logo Configuration](/deploystack/application-logo-configuration) page. diff --git a/docs/deploystack/deploystack-configuration-directory.mdx b/docs/deploystack/deploystack-configuration-directory.mdx index fd13942..c178cbe 100644 --- a/docs/deploystack/deploystack-configuration-directory.mdx +++ b/docs/deploystack/deploystack-configuration-directory.mdx @@ -5,7 +5,7 @@ description: Technical guide for setting up the .deploystack directory to manage # .deploystack Directory Reference -The `.deploystack` directory in your repository contains configuration files that DeployStack uses to generate and maintain your Infrastructure as Code templates. Creating this repo allows you to enable the [lifecycle of IaC](/docs/deploystack/iac-lifecycle). The deploystack configurations repo only makes sense if you also [install DeployStack GitHub app](/docs/deploystack/github-application). Otherwise, changes to DeployStack backend will not be recognized. +The `.deploystack` directory in your repository contains configuration files that DeployStack uses to generate and maintain your Infrastructure as Code templates. Creating this repo allows you to enable the [lifecycle of IaC](/deploystack/iac-lifecycle). The deploystack configurations repo only makes sense if you also [install DeployStack GitHub app](/deploystack/github-application). Otherwise, changes to DeployStack backend will not be recognized. `.deploystack` directory is optional. You don't need to create it to submit your repository to deploystack.io. @@ -24,7 +24,7 @@ The `.deploystack` directory in your repository contains configuration files tha ### DeployStack Configuration File -Please read more at [DeployStack Configuration File Reference](/docs/deploystack/deploystack-config-file). +Please read more at [DeployStack Configuration File Reference](/deploystack/deploystack-config-file). ### Docker Configuration @@ -52,11 +52,11 @@ docker run -d -p 80:80 nginx:alpine ### Environment Variables -Please read more from our [environment variables](/docs/deploystack/docker-environment-variables) page. +Please read more from our [environment variables](/deploystack/docker-environment-variables) page. ## Automatic Updates -When the [DeployStack GitHub App](/docs/deploystack/github-application) is installed: +When the [DeployStack GitHub App](/deploystack/github-application) is installed: 1. Changes to specific (`docker-compose.yml` & `docker-run.txt`) file in `.deploystack/` trigger template updates 2. Updates only process when changes occur on the default branch @@ -66,6 +66,6 @@ When the [DeployStack GitHub App](/docs/deploystack/github-application) is insta - The `.deploystack` directory is **optional** - Without this directory, automatic template updates are **not** available -- You can add the directory and install the [DeployStack GitHub Sync App](/docs/deploystack/github-application) at any time -- [Environment variables](/docs/deploystack/docker-environment-variables) and [DeployStack config](/docs/deploystack/deploystack-config-file) are optional components +- You can add the directory and install the [DeployStack GitHub Sync App](/deploystack/github-application) at any time +- [Environment variables](/deploystack/docker-environment-variables) and [DeployStack config](/deploystack/deploystack-config-file) are optional components - Only one Docker configuration file should be used (either compose or run) diff --git a/docs/deploystack/docker-compose-requirements.mdx b/docs/deploystack/docker-compose-requirements.mdx index a54cf11..eb91b87 100644 --- a/docs/deploystack/docker-compose-requirements.mdx +++ b/docs/deploystack/docker-compose-requirements.mdx @@ -12,7 +12,7 @@ DeployStack is designed to work with Docker Compose files that meet specific req Your `docker-compose.yml` file must: 1. Use pre-built Docker images -2. Reference public images from Docker Hub or another registries -> check [Supported Registries](/docs/docker-to-iac/supported-registries) +2. Reference public images from Docker Hub or another registries -> check [Supported Registries](/docker-to-iac/supported-registries) 3. Be a valid Docker Compose file (version 3 and above) Your docker-compose file does not necessarily have to be called `docker-compose.yml` and does not have to be located in the root directory. You can rename your docker compose file and store it in any sub directory. @@ -53,7 +53,7 @@ The infrastructure templates we generate require specific, immutable container i ## Supported Docker Compose Properties -We currently support these Docker Compose properties -> please check [Supported Docker Compose Variables](/docs/docker-to-iac/supported-docker-compose-variables). +We currently support these Docker Compose properties -> please check [Supported Docker Compose Variables](/docker-to-iac/supported-docker-compose-variables). ### Kubernetes/Helm @@ -74,19 +74,19 @@ DeployStack can handle Docker Compose files with multiple services, but support - Others will only deploy the first service in your compose file - Kubernetes (Helm) supports multi-service deployments with each service becoming a separate Deployment -Check the specific [Multi Services Support](/docs/docker-to-iac/multi-services-support) for details about multi-service support. +Check the specific [Multi Services Support](/docker-to-iac/multi-services-support) for details about multi-service support. ## Working with Private Images Currently, DeployStack only supports public images from Docker Hub. If you need to use private images: -1. Make your images public on Docker Hub or [other supported registries](/docs/docker-to-iac/supported-registries) +1. Make your images public on Docker Hub or [other supported registries](/docker-to-iac/supported-registries) 2. Update your docker-compose.yml to reference the public images 3. Submit your repository to DeployStack ## Environment Variables -Please read more from our [environment variables](/docs/deploystack/docker-environment-variables) page. +Please read more from our [environment variables](/deploystack/docker-environment-variables) page. ## Validation @@ -98,5 +98,5 @@ When you submit your repository, we perform these checks: ## Next Steps -- See how [One-Click Deploy](/docs/deploystack/one-click-deploy) works -- Check the [Troubleshooting](/docs/deploystack/troubleshooting) guide if you run into issues +- See how [One-Click Deploy](/deploystack/one-click-deploy) works +- Check the [Troubleshooting](/deploystack/troubleshooting) guide if you run into issues diff --git a/docs/deploystack/getting-started.mdx b/docs/deploystack/getting-started.mdx index 19d10f4..c441f15 100644 --- a/docs/deploystack/getting-started.mdx +++ b/docs/deploystack/getting-started.mdx @@ -99,7 +99,7 @@ Create a `.deploystack` directory in your repository with these components: - `docker-run.txt`: Alternative to compose file, contains your Docker run command - Only one of these files should be present -For more configuration options please check our [.deploystack Directory Reference](/docs/deploystack/deploystack-configuration-directory). +For more configuration options please check our [.deploystack Directory Reference](/deploystack/deploystack-configuration-directory). ### GitHub App Integration @@ -189,6 +189,6 @@ After template generation: ## Need Additional Help? -- Review our detailed [Troubleshooting Guide](/docs/deploystack/troubleshooting) +- Review our detailed [Troubleshooting Guide](/deploystack/troubleshooting) - Join our active [Discord Community](https://discord.gg/UjFWwByB) - Submit issues on GitHub to our [Feedback repository](https://github.com/deploystackio/feedback) diff --git a/docs/deploystack/github-application.mdx b/docs/deploystack/github-application.mdx index 0bfd545..8fe39a4 100644 --- a/docs/deploystack/github-application.mdx +++ b/docs/deploystack/github-application.mdx @@ -11,7 +11,7 @@ The DeployStack GitHub App ensures your Infrastructure as Code (IaC) templates r When you install the [DeployStack Repository Sync](https://github.com/apps/deploystack-repository-sync) app, it monitors specific files in your repository: -- `.deploystack/` directory - [Contains your Docker configurations and assets](/docs/deploystack/deploystack-configuration-directory) +- `.deploystack/` directory - [Contains your Docker configurations and assets](/deploystack/deploystack-configuration-directory) - `README.md` - For README.md updates When changes are detected in these files, the app automatically triggers an update of your IaC templates in our [deploy-templates](https://github.com/deploystackio/deploy-templates) repository. @@ -47,12 +47,12 @@ When the app detects changes, it automatically updates: - Repository Homepage - Description - IaC templates - - Depends on which technique (docker compose or docker run command) you choose, you can upload the `docker-compose.yml` or `docker-run.txt` in the `.deploystack` directory. Every time you update the files on your main branch (or additional branch), IaC templates will be updated automatically - [Automatic Updates](/docs/deploystack/deploystack-configuration-directory#automatic-updates). + - Depends on which technique (docker compose or docker run command) you choose, you can upload the `docker-compose.yml` or `docker-run.txt` in the `.deploystack` directory. Every time you update the files on your main branch (or additional branch), IaC templates will be updated automatically - [Automatic Updates](/deploystack/deploystack-configuration-directory#automatic-updates). - Environment variables - - To make it easier for a user to deploy IaC templates, it is recommended to work with environment variables. For this purpose, you can upload an `env` file and add your appropriate variables - [Environment Variables](/docs/deploystack/deploystack-configuration-directory#environment-variables). + - To make it easier for a user to deploy IaC templates, it is recommended to work with environment variables. For this purpose, you can upload an `env` file and add your appropriate variables - [Environment Variables](/deploystack/deploystack-configuration-directory#environment-variables). - DeployStack Configuration - Project / Applicaton Logo - - It is possible to upload your own logo to DeployStack catalog. To do this you need to upload a file to our directory `.deploystack`. Read more about it here: [Repository Logo](/docs/deploystack/deploystack-configuration-directory#repository-logo) + - It is possible to upload your own logo to DeployStack catalog. To do this you need to upload a file to our directory `.deploystack`. Read more about it here: [Repository Logo](/deploystack/deploystack-configuration-directory#repository-logo) ## Managing the Integration @@ -66,4 +66,4 @@ After installing the app: 2. Commit and push your changes 3. DeployStack will automatically update your deployment templates -For details about the `.deploystack` directory structure, check our [.deploystack Directory Reference](/docs/deploystack/deploystack-configuration-directory). +For details about the `.deploystack` directory structure, check our [.deploystack Directory Reference](/deploystack/deploystack-configuration-directory). diff --git a/docs/deploystack/iac-lifecycle.mdx b/docs/deploystack/iac-lifecycle.mdx index e9e551f..6341728 100644 --- a/docs/deploystack/iac-lifecycle.mdx +++ b/docs/deploystack/iac-lifecycle.mdx @@ -11,7 +11,7 @@ This guide explains how DeployStack manages and updates your Infrastructure as C ### Initial Setup -1. Create a `.deploystack` [configuration directory](/docs/deploystack/deploystack-configuration-directory) in your repository +1. Create a `.deploystack` [configuration directory](/deploystack/deploystack-configuration-directory) in your repository 2. Add your Docker configuration files: - `docker-compose.yml` for Compose configurations - `docker-run.txt` for Docker run commands @@ -20,7 +20,7 @@ This guide explains how DeployStack manages and updates your Infrastructure as C ### Enabling Automatic Updates -Install the [DeployStack Repository Sync](/docs/deploystack/github-application) GitHub App to keep your templates up to date when: +Install the [DeployStack Repository Sync](/deploystack/github-application) GitHub App to keep your templates up to date when: - You modify Docker configurations in the `.deploystack` directory - Cloud providers update their IaC specifications @@ -36,7 +36,7 @@ All IaC templates are stored in public and open-source repository: [https://gith ### Prerequisites for activating the flow -1. You have installed the [DeployStack GitHub app](/docs/deploystack/github-application). +1. You have installed the [DeployStack GitHub app](/deploystack/github-application). 2. You have created the `.deploystack/docker-run.txt` or `.deploystack/docker-compose.yml` file. The choice between `docker-run.txt` or `docker-compose.yml` depends on the submission process used to DeployStack. When submitting to DeployStack, you can choose two methods -> Docker Run or Docker Compose. diff --git a/docs/deploystack/index.mdx b/docs/deploystack/index.mdx index 58ffd00..2203faa 100644 --- a/docs/deploystack/index.mdx +++ b/docs/deploystack/index.mdx @@ -10,14 +10,14 @@ DeployStack helps you deploy Docker Compose and Docker Run applications across d ## Documentation Sections -- [Getting Started](/docs/deploystack/getting-started.md) - Quick introduction and first steps -- [Docker Compose Requirements](/docs/deploystack/docker-compose-requirements.md) - Learn about supported configurations -- [One-Click Deploy](/docs/deploystack/one-click-deploy.md) - Learn about deployment automation -- [Troubleshooting](/docs/deploystack/troubleshooting.md) - Resolve common issues +- [Getting Started](/deploystack/getting-started) - Quick introduction and first steps +- [Docker Compose Requirements](/deploystack/docker-compose-requirements) - Learn about supported configurations +- [One-Click Deploy](/deploystack/one-click-deploy) - Learn about deployment automation +- [Troubleshooting](/deploystack/troubleshooting) - Resolve common issues ## Additional Resources -- [Docker-to-IaC Module Documentation](/docs/docker-to-iac/index.md) +- [Docker-to-IaC Module Documentation](/docker-to-iac/index) - [Join our Discord](https://discord.gg/UjFWwByB) - [Visit DeployStack](https://deploystack.io) diff --git a/docs/deploystack/multiple-branches.mdx b/docs/deploystack/multiple-branches.mdx index ddb2f35..e05520f 100644 --- a/docs/deploystack/multiple-branches.mdx +++ b/docs/deploystack/multiple-branches.mdx @@ -20,7 +20,7 @@ Every repository starts with its default branch (typically `main` or `master`). When you change your default branch in GitHub: -- DeployStack automatically detects the change - you need to install [DeployStack GitHub App](/docs/deploystack/github-application) +- DeployStack automatically detects the change - you need to install [DeployStack GitHub App](/deploystack/github-application) - Regenerates templates for the new default branch - Updates all deployment buttons @@ -80,7 +80,7 @@ This structure allows you to: - Modify service configurations independently - Keep each version's deployment parameters isolated -Remember: The DeployStack GitHub App only monitors the standard filenames: check [.deploystack Directory Reference for more info](/docs/deploystack/deploystack-configuration-directory) +Remember: The DeployStack GitHub App only monitors the standard filenames: check [.deploystack Directory Reference for more info](/deploystack/deploystack-configuration-directory) ## Real-World Example @@ -142,7 +142,7 @@ This strategy allows your users to: - Maximum of 5 active branches supported - Each branch can have unique Docker configurations - Default branch can be changed (switch to another branch and make it default) but not excluded -- Branch configurations ([DeployStack config file](/docs/deploystack/deploystack-config-file)) must be in the default branch +- Branch configurations ([DeployStack config file](/deploystack/deploystack-config-file)) must be in the default branch - All branches are automatically monitored for changes - Template regeneration happens automatically when: - Branch content changes diff --git a/docs/deploystack/one-click-deploy.mdx b/docs/deploystack/one-click-deploy.mdx index 8cf961e..3f42931 100644 --- a/docs/deploystack/one-click-deploy.mdx +++ b/docs/deploystack/one-click-deploy.mdx @@ -11,7 +11,7 @@ DeployStack leverages existing deployment technologies from cloud providers to m When you submit your repository to [deploystack.io/submit](https://deploystack.io/submit), we: -1. Generate Infrastructure as Code (IaC) templates for [supported cloud providers](/docs/docker-to-iac/index) +1. Generate Infrastructure as Code (IaC) templates for [supported cloud providers](/docker-to-iac/index) 2. Store these templates in our [deploy-templates repository](https://github.com/deploystackio/deploy-templates) 3. Create provider-specific deployment buttons for your README.md -> by [deploystack.io/deploy-button](https://deploystack.io/deploy-button) @@ -41,7 +41,7 @@ We integrate with cloud providers' native deployment systems. For example: - **DigitalOcean**: Uses the "Deploy to DigitalOcean" functionality as documented in their [official guide](https://docs.digitalocean.com/products/app-platform/how-to/add-deploy-do-button/) - **Kubernetes**: Generates Helm charts that can be deployed to any Kubernetes cluster -- Check [supported cloud providers](/docs/docker-to-iac/index) for full list +- Check [supported cloud providers](/docker-to-iac/index) for full list ### Provider-Specific Templates diff --git a/docs/deploystack/troubleshooting.mdx b/docs/deploystack/troubleshooting.mdx index 15bb2aa..c125d48 100644 --- a/docs/deploystack/troubleshooting.mdx +++ b/docs/deploystack/troubleshooting.mdx @@ -81,7 +81,7 @@ The submitted docker-compose file doesn't meet the required format or contains u **Solution:** - Validate your docker-compose file syntax -- Check our [Docker Compose Requirements](/docs/deploystack/docker-compose-requirements) page +- Check our [Docker Compose Requirements](/deploystack/docker-compose-requirements) page - Ensure you're using supported features only ## Error Converting Docker Compose to IaC @@ -97,7 +97,7 @@ This error occurs when our system cannot convert your docker-compose configurati **Solution:** - Simplify your docker-compose configuration -- Review our [supported features documentation](/docs/docker-to-iac/supported-docker-compose-variables) +- Review our [supported features documentation](/docker-to-iac/supported-docker-compose-variables) - Ensure all services use supported configurations ## Error Listing Services from Docker Compose @@ -138,7 +138,7 @@ This indicates an unexpected error in our validation process. ## General Troubleshooting Tips 1. Validate your docker-compose file locally before submission -2. Ensure your repository meets all [requirements](/docs/deploystack/docker-compose-requirements) +2. Ensure your repository meets all [requirements](/deploystack/docker-compose-requirements) 3. Check that all services use supported configurations 4. Verify your repository is public and accessible @@ -147,5 +147,5 @@ This indicates an unexpected error in our validation process. If you're still experiencing issues: - Join our [Discord community](https://discord.gg/UjFWwByB) -- Check our [Docker Compose Requirements](/docs/deploystack/docker-compose-requirements) -- Review [supported features](/docs/docker-to-iac/supported-docker-compose-variables) +- Check our [Docker Compose Requirements](/deploystack/docker-compose-requirements) +- Review [supported features](/docker-to-iac/supported-docker-compose-variables) diff --git a/docs/docker-to-iac/api.mdx b/docs/docker-to-iac/api.mdx index 8aaff08..faa0160 100644 --- a/docs/docker-to-iac/api.mdx +++ b/docs/docker-to-iac/api.mdx @@ -83,7 +83,7 @@ console.log(parsers); ] ``` -**Note the files array**: that's because we have a [multi file strategy](/docs/docker-to-iac/multi-file-configuration). +**Note the files array**: that's because we have a [multi file strategy](/docker-to-iac/multi-file-configuration). ### Type diff --git a/docs/docker-to-iac/example-of-a-new-parser.mdx b/docs/docker-to-iac/example-of-a-new-parser.mdx index 571f608..85242da 100644 --- a/docs/docker-to-iac/example-of-a-new-parser.mdx +++ b/docs/docker-to-iac/example-of-a-new-parser.mdx @@ -343,7 +343,7 @@ const parsers: BaseParser[] = [ ## Testing -Please read our guidelines for testing parsers in the [Testing section](/docs/docker-to-iac/testing). +Please read our guidelines for testing parsers in the [Testing section](/docker-to-iac/testing). ## New parser documentation diff --git a/docs/docker-to-iac/index.mdx b/docs/docker-to-iac/index.mdx index 3d425b6..2fea713 100644 --- a/docs/docker-to-iac/index.mdx +++ b/docs/docker-to-iac/index.mdx @@ -1,7 +1,7 @@ --- title: Docker to Infrastructure 2 description: Introduction to the node module docker-to-iac which allows you to transfer docker-compose into IaC templates -sidebar: lol text +sidebar: docker-to-iac --- # Docker to Infrastructure as Code Module @@ -39,7 +39,7 @@ After the successful translation, you can deploy your containers to your cloud p - Only pre-build container possible -Please read more at the [limitations page](/docs/docker-to-iac/limitations.md) +Please read more at the [limitations page](/docker-to-iac/limitations) ## Help wanted diff --git a/docs/docker-to-iac/limitations.mdx b/docs/docker-to-iac/limitations.mdx index 8ba65ba..8072dea 100644 --- a/docs/docker-to-iac/limitations.mdx +++ b/docs/docker-to-iac/limitations.mdx @@ -7,7 +7,7 @@ description: Current limitations and constraints of the docker-to-iac module ## Registry Support -The module currently supports Docker images from -> please check [Supported Registries for docker-to-iac module](/docs/docker-to-iac/supported-registries.md) +The module currently supports Docker images from -> please check [Supported Registries for docker-to-iac module](/docker-to-iac/supported-registries) ## Docker Image Requirement diff --git a/docs/docker-to-iac/multi-services-support.mdx b/docs/docker-to-iac/multi-services-support.mdx index 9645e4e..209a897 100644 --- a/docs/docker-to-iac/multi-services-support.mdx +++ b/docs/docker-to-iac/multi-services-support.mdx @@ -5,7 +5,7 @@ description: Learn about multi-service deployment support - See how docker-to-ia # Multi-Service Support -Multi-service support refers to the ability of a [parser](/docs/docker-to-iac/parser-explanation) to handle multiple container configurations when translating to Infrastructure as Code (IaC) templates. +Multi-service support refers to the ability of a [parser](/docker-to-iac/parser-explanation) to handle multiple container configurations when translating to Infrastructure as Code (IaC) templates. ## Docker Run vs Docker Compose @@ -73,6 +73,6 @@ const translation = translate(dockerComposeContent, { ## Provider-Specific Behavior -Before using a specific parser, check its multi-service capabilities in the [parser documentation](/docs/docker-to-iac/parser-explanation). This helps ensure your deployment strategy aligns with the provider's capabilities. +Before using a specific parser, check its multi-service capabilities in the [parser documentation](/docker-to-iac/parser-explanation). This helps ensure your deployment strategy aligns with the provider's capabilities. Note that some providers may have different service limits or deployment patterns even when they support multiple services. Always consult the target provider's documentation for specific limitations. diff --git a/docs/docker-to-iac/parser-explanation.mdx b/docs/docker-to-iac/parser-explanation.mdx index ca69734..c97a29c 100644 --- a/docs/docker-to-iac/parser-explanation.mdx +++ b/docs/docker-to-iac/parser-explanation.mdx @@ -32,7 +32,7 @@ services: ## API -For detailed API documentation, see the [parser API reference](/docs/docker-to-iac/api). +For detailed API documentation, see the [parser API reference](/docker-to-iac/api). ## Default Parser Config @@ -40,7 +40,7 @@ Each parser includes default configurations specific to its target cloud provide Example: AWS Fargate has a minimum CPU allocation of 256, while DigitalOcean's [minimum setting is 1 vCPU](https://www.digitalocean.com/pricing/app-platform). The default parser config handles these provider-specific requirements. -To retrieve default parser configurations through the API, see the [parser info documentation](/docs/docker-to-iac/api#get-parser-info). +To retrieve default parser configurations through the API, see the [parser info documentation](/docker-to-iac/api#get-parser-info). ## Parser vs. Language @@ -52,7 +52,7 @@ For example, AWS infrastructure can be defined using: - AWS CDK (for TypeScript, Python, etc.) - Terraform -When adding new parsers, consider whether multiple IaC languages are possible for your target provider. This affects how you name your parser file in `src/parsers/.ts`. It's why the [`translate()`](/docs/docker-to-iac/api#translate-api) method requires the target IaC language name (e.g., `CFN`) rather than the provider name (e.g., `AWS`). +When adding new parsers, consider whether multiple IaC languages are possible for your target provider. This affects how you name your parser file in `src/parsers/.ts`. It's why the [`translate()`](/docker-to-iac/api#translate-api) method requires the target IaC language name (e.g., `CFN`) rather than the provider name (e.g., `AWS`). ## Parser Implementation Notes diff --git a/docs/docker-to-iac/parser/aws-cloudformation.mdx b/docs/docker-to-iac/parser/aws-cloudformation.mdx index 30861bb..408e380 100644 --- a/docs/docker-to-iac/parser/aws-cloudformation.mdx +++ b/docs/docker-to-iac/parser/aws-cloudformation.mdx @@ -90,7 +90,7 @@ For applications requiring persistent storage, consider: Multi `services` support for CloudFormation: __yes__ -Please read more about [multi service support here](/docs/docker-to-iac/multi-services-support). +Please read more about [multi service support here](/docker-to-iac/multi-services-support). This CloudFormation template is designed for development and testing environments. For production deployments, review and adjust security groups, storage configuration, and other security settings according to your requirements. diff --git a/docs/docker-to-iac/parser/digitalocean.mdx b/docs/docker-to-iac/parser/digitalocean.mdx index 5ea2624..c5b9eaf 100644 --- a/docs/docker-to-iac/parser/digitalocean.mdx +++ b/docs/docker-to-iac/parser/digitalocean.mdx @@ -186,4 +186,4 @@ Multi `services` support for DigitalOcean: __yes__ DigitalOcean supports multiple services in a single App Spec file. -Please read more about [multi service support here](/docs/docker-to-iac/multi-services-support). +Please read more about [multi service support here](/docker-to-iac/multi-services-support). diff --git a/docs/docker-to-iac/parser/helm.mdx b/docs/docker-to-iac/parser/helm.mdx index b99c6ea..5c397d4 100644 --- a/docs/docker-to-iac/parser/helm.mdx +++ b/docs/docker-to-iac/parser/helm.mdx @@ -170,7 +170,7 @@ Multi `services` support for Helm: **yes** Helm Charts are designed to handle multiple services and dependencies in a single deployment, making them ideal for complex applications. The parser transforms all services from your Docker Compose file into corresponding Kubernetes resources. -Please read more about [multi service support here](/docs/docker-to-iac/multi-services-support). +Please read more about [multi service support here](/docker-to-iac/multi-services-support). ## Deployment Instructions diff --git a/docs/docker-to-iac/parser/index.mdx b/docs/docker-to-iac/parser/index.mdx index 87c45ce..f00e214 100644 --- a/docs/docker-to-iac/parser/index.mdx +++ b/docs/docker-to-iac/parser/index.mdx @@ -6,9 +6,9 @@ menuTitle: Available parser # Available parser list for module docker-to-iac -Here you can find the list of available [parsers](/docs/docker-to-iac/parser-explanation.md): +Here you can find the list of available [parsers](/docker-to-iac/parser-explanation): -- [AWS CloudFormation](/docs/docker-to-iac/parser/aws-cloudformation.md) -- [Render.com](/docs/docker-to-iac/parser/render.com.md) -- [DigitalOcean](/docs/docker-to-iac/parser/digitalocean.md) -- [Helm (Kubernetes)](/docs/docker-to-iac/parser/helm.md) +- [AWS CloudFormation](/docker-to-iac/parser/aws-cloudformation) +- [Render.com](/docker-to-iac/parser/render.com) +- [DigitalOcean](/docker-to-iac/parser/digitalocean) +- [Helm (Kubernetes)](/docker-to-iac/parser/helm) diff --git a/docs/docker-to-iac/parser/render.com.mdx b/docs/docker-to-iac/parser/render.com.mdx index 926c2fe..771e914 100644 --- a/docs/docker-to-iac/parser/render.com.mdx +++ b/docs/docker-to-iac/parser/render.com.mdx @@ -122,7 +122,7 @@ services: ### Adding New Service Types -If you're using a service that should be private but isn't automatically detected, please visit our [Render: Contributing to Render Service Types docs page](/docs/docker-to-iac/render-contributing-to-service-types). +If you're using a service that should be private but isn't automatically detected, please visit our [Render: Contributing to Render Service Types docs page](/docker-to-iac/render-contributing-to-service-types). ## Multi Services Support @@ -130,4 +130,4 @@ Multi `services` support for Render.com: __yes__ Since [multi services](https://render.com/docs/blueprint-spec#root-level-fields) feature is supported. -Please read more about [multi service support here](/docs/docker-to-iac/multi-services-support). +Please read more about [multi service support here](/docker-to-iac/multi-services-support). diff --git a/docs/docker-to-iac/project-structure.mdx b/docs/docker-to-iac/project-structure.mdx index 1c4126c..d794149 100644 --- a/docs/docker-to-iac/project-structure.mdx +++ b/docs/docker-to-iac/project-structure.mdx @@ -168,8 +168,8 @@ Tests for individual components: ## Adding New Parser -Please check our [Adding a New Parser](/docs/docker-to-iac/example-of-a-new-parser) documentation for detailed instructions on how to add a new parser to the project. This includes creating a new parser file, implementing the parsing logic, and ensuring compatibility with existing configurations. +Please check our [Adding a New Parser](/docker-to-iac/example-of-a-new-parser) documentation for detailed instructions on how to add a new parser to the project. This includes creating a new parser file, implementing the parsing logic, and ensuring compatibility with existing configurations. ### Adding New Tests -Please refer to the [Testing](/docs/docker-to-iac/testing) documentation for guidelines on adding new tests, including unit and end-to-end tests. +Please refer to the [Testing](/docker-to-iac/testing) documentation for guidelines on adding new tests, including unit and end-to-end tests. diff --git a/docs/docker-to-iac/quickstart.mdx b/docs/docker-to-iac/quickstart.mdx index 67009de..a958678 100644 --- a/docs/docker-to-iac/quickstart.mdx +++ b/docs/docker-to-iac/quickstart.mdx @@ -61,4 +61,4 @@ When using the `translate` function, you can specify: - `target`: The IaC language to translate to (e.g., 'CFN' for AWS CloudFormation) - `templateFormat`: Output format - 'json', 'yaml', or 'text' -For a complete list of supported parsers and formats, visit the [API documentation](/docs/docker-to-iac/api). +For a complete list of supported parsers and formats, visit the [API documentation](/docker-to-iac/api). diff --git a/docs/index.mdx b/docs/index.mdx index f89e880..a553c26 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -17,32 +17,32 @@ DeployStack simplifies cloud deployment through three key steps: configure your ### Core Concepts -} title="Quickstart" href="/docs/deploystack/getting-started"> +} title="Quickstart" href="/deploystack/getting-started"> Start with our Getting Started Guide to understand the basics of DeployStack. -} title="One-Click Deploy" href="/docs/deploystack/one-click-deploy"> +} title="One-Click Deploy" href="/deploystack/one-click-deploy"> Learn how to enable One-Click Deploy buttons for your repository. -} title="Configuration" href="/docs/deploystack/deploystack-configuration-directory"> +} title="Configuration" href="/deploystack/deploystack-configuration-directory"> Configuration file placed to your repository, telling Zerops how to build and start your app. ### Supported Cloud Providers -DeployStack generates infrastructure templates for major cloud providers, each optimized for their specific deployment patterns. AWS CloudFormation templates use Fargate for containerized workloads, DigitalOcean leverages App Platform, and Render.com implements Blueprints for smooth deployment. While translating your docker command to Infrastructure as Code by using [docker-to-iac](/docs/docker-to-iac/index.md) module, you can choose your target provider. +DeployStack generates infrastructure templates for major cloud providers, each optimized for their specific deployment patterns. AWS CloudFormation templates use Fargate for containerized workloads, DigitalOcean leverages App Platform, and Render.com implements Blueprints for smooth deployment. While translating your docker command to Infrastructure as Code by using [docker-to-iac](/docker-to-iac/index) module, you can choose your target provider. - + AWS - + DigitalOcean - + Render.com - + Helm @@ -80,4 +80,4 @@ Visit our [GitHub repository](https://github.com/deploystackio/docker-to-iac) to ## Community and Support - Join our [Discord community](https://discord.gg/UjFWwByB) -- Check our [troubleshooting guide](/docs/deploystack/troubleshooting.md) +- Check our [troubleshooting guide](/deploystack/troubleshooting) diff --git a/lib/source.ts b/lib/source.ts index 56e6e00..18e4e4e 100644 --- a/lib/source.ts +++ b/lib/source.ts @@ -10,10 +10,9 @@ import { DeployStackLogo } from './components/DeployStackLogo'; export const source = loader({ // Base URL for the documentation pages. - // Since 'docs/index.md' should be the root page of the /docs section, - // and our content is in the 'docs' directory (configured in source.config.ts), - // baseUrl should be '/docs'. This means docs/index.mdx will be at /docs. - baseUrl: '/docs', + // Since we've moved docs to the root level, baseUrl should be '/' + // This means docs/index.mdx will be at / and other docs at their direct paths + baseUrl: '/', // The source of the documents, converted to Fumadocs format. source: docs.toFumadocsSource(), From bc484149934b0660fbad0ce44b6c54e76df3c1b9 Mon Sep 17 00:00:00 2001 From: JasonKrik Date: Wed, 18 Jun 2025 16:51:34 +0200 Subject: [PATCH 08/17] refactor: enhance local file checking for markdown links --- check-links.js | 39 ++++++++++++++++++++++++++++----------- 1 file changed, 28 insertions(+), 11 deletions(-) diff --git a/check-links.js b/check-links.js index 914131f..6d9d8fe 100644 --- a/check-links.js +++ b/check-links.js @@ -25,19 +25,35 @@ const extractLinks = (content) => { // Check if a local file exists const checkLocalFile = (linkPath, filePath) => { - if (linkPath.startsWith('/docs/')) { + // Check for internal links (starting with / but not external URLs) + if (linkPath.startsWith('/') && !linkPath.startsWith('//') && !linkPath.startsWith('http')) { // Remove hash fragment before checking file existence const [baseUrl] = linkPath.split('#'); - const localPath = path.join(process.cwd(), baseUrl); - try { - fs.accessSync(localPath, fs.constants.F_OK); - console.log(` ✅ ${linkPath}`); - return true; - } catch (err) { - console.log(` ❌ ${linkPath} → File not found`); - return false; + // Map the URL to the actual file location + // Since our URLs are now root-level but files are in docs/ + const actualFilePath = path.join(process.cwd(), 'docs', baseUrl.substring(1)); + + // Try both .mdx and .md extensions + const possiblePaths = [ + actualFilePath + '.mdx', + actualFilePath + '.md', + path.join(actualFilePath, 'index.mdx'), + path.join(actualFilePath, 'index.md') + ]; + + for (const possiblePath of possiblePaths) { + try { + fs.accessSync(possiblePath, fs.constants.F_OK); + console.log(` ✅ ${linkPath}`); + return true; + } catch (err) { + // Continue to next possible path + } } + + console.log(` ❌ ${linkPath} → File not found (checked: ${possiblePaths.map(p => path.relative(process.cwd(), p)).join(', ')})`); + return false; } return null; // not a local file }; @@ -79,7 +95,8 @@ const processFile = async (filePath) => { let allValid = true; for (const link of links) { - if (link.url.startsWith('/docs/')) { + if (link.url.startsWith('/') && !link.url.startsWith('//') && !link.url.startsWith('http')) { + // Internal link (root-level) const isValid = checkLocalFile(link.url, filePath); if (!isValid) allValid = false; } else if (link.url.startsWith('http')) { @@ -109,7 +126,7 @@ const processDirectory = async (dir) => { if (stat.isDirectory()) { const isValid = await processDirectory(filePath); if (!isValid) allValid = false; - } else if (file.endsWith('.md')) { + } else if (file.endsWith('.md') || file.endsWith('.mdx')) { const isValid = await processFile(filePath); if (!isValid) allValid = false; } From 4c386d6269ec2efb665ba9b6e0324f489a107001 Mon Sep 17 00:00:00 2001 From: JasonKrik Date: Wed, 18 Jun 2025 17:12:55 +0200 Subject: [PATCH 09/17] chore: remove outdated documentation files for project structure, publishing to npm, quickstart guide, render service types, service connections, supported docker compose variables, supported registries, and testing feat: add sitemap generation for dynamic pages in Next.js application --- app/sitemap.ts | 30 + .../application-logo-configuration.mdx | 60 -- .../deploystack/deploystack-config-file.mdx | 259 ------ .../deploystack-configuration-directory.mdx | 71 -- .../docker-compose-requirements.mdx | 102 --- .../docs/deploystack/getting-started.mdx | 194 ----- .../docs/deploystack/github-application.mdx | 69 -- .../docs/deploystack/iac-lifecycle.mdx | 88 -- .../docs/deploystack/index.mdx | 23 - .../docs/deploystack/multiple-branches.mdx | 150 ---- .../docs/deploystack/one-click-deploy.mdx | 157 ---- .../docs/deploystack/troubleshooting.mdx | 151 ---- .../docs/docker-to-iac/api.mdx | 790 ----------------- .../docker-to-iac/example-of-a-new-parser.mdx | 383 --------- .../docs/docker-to-iac/index.mdx | 50 -- .../docs/docker-to-iac/limitations.mdx | 89 -- .../docker-to-iac/multi-services-support.mdx | 78 -- .../docs/docker-to-iac/parser-explanation.mdx | 61 -- .../parser/aws-cloudformation.mdx | 97 --- .../docker-to-iac/parser/digitalocean.mdx | 189 ----- .../docs/docker-to-iac/parser/helm.mdx | 210 ----- .../docs/docker-to-iac/parser/index.mdx | 14 - .../docs/docker-to-iac/parser/render.com.mdx | 133 --- .../docs/docker-to-iac/project-structure.mdx | 175 ---- .../docs/docker-to-iac/quickstart.mdx | 64 -- .../docs/index.mdx | 83 -- lib/seo-utils.ts | 6 +- tmp/docker-to-iac/api.mdx | 791 ------------------ tmp/docker-to-iac/available-commands.mdx | 78 -- tmp/docker-to-iac/before-you-start.mdx | 31 - .../environment-variable-generation.mdx | 209 ----- tmp/docker-to-iac/environment-variable.mdx | 199 ----- tmp/docker-to-iac/example-of-a-new-parser.mdx | 384 --------- tmp/docker-to-iac/limitations.mdx | 90 -- tmp/docker-to-iac/meta.json | 5 - .../multi-file-configuration.mdx | 192 ----- tmp/docker-to-iac/multi-services-support.mdx | 79 -- tmp/docker-to-iac/parser-explanation.mdx | 62 -- .../parser/aws-cloudformation.mdx | 96 --- tmp/docker-to-iac/parser/digitalocean.mdx | 187 ----- tmp/docker-to-iac/parser/helm.mdx | 211 ----- tmp/docker-to-iac/parser/index.mdx | 14 - tmp/docker-to-iac/parser/render.com.mdx | 133 --- tmp/docker-to-iac/project-structure.mdx | 176 ---- tmp/docker-to-iac/publishing-to-npm.mdx | 84 -- tmp/docker-to-iac/quickstart.mdx | 65 -- .../render-contributing-to-service-types.mdx | 147 ---- tmp/docker-to-iac/service-connections.mdx | 227 ----- .../supported-docker-compose-variables.mdx | 84 -- tmp/docker-to-iac/supported-registries.mdx | 84 -- tmp/docker-to-iac/testing.mdx | 328 -------- 51 files changed, 33 insertions(+), 7699 deletions(-) create mode 100644 app/sitemap.ts delete mode 100644 docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/application-logo-configuration.mdx delete mode 100644 docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/deploystack-config-file.mdx delete mode 100644 docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/deploystack-configuration-directory.mdx delete mode 100644 docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/docker-compose-requirements.mdx delete mode 100644 docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/getting-started.mdx delete mode 100644 docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/github-application.mdx delete mode 100644 docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/iac-lifecycle.mdx delete mode 100644 docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/index.mdx delete mode 100644 docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/multiple-branches.mdx delete mode 100644 docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/one-click-deploy.mdx delete mode 100644 docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/troubleshooting.mdx delete mode 100644 docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/api.mdx delete mode 100644 docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/example-of-a-new-parser.mdx delete mode 100644 docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/index.mdx delete mode 100644 docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/limitations.mdx delete mode 100644 docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/multi-services-support.mdx delete mode 100644 docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/parser-explanation.mdx delete mode 100644 docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/parser/aws-cloudformation.mdx delete mode 100644 docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/parser/digitalocean.mdx delete mode 100644 docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/parser/helm.mdx delete mode 100644 docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/parser/index.mdx delete mode 100644 docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/parser/render.com.mdx delete mode 100644 docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/project-structure.mdx delete mode 100644 docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/quickstart.mdx delete mode 100644 docs-backup-2025-06-18T14-33-44-828Z/docs/index.mdx delete mode 100644 tmp/docker-to-iac/api.mdx delete mode 100644 tmp/docker-to-iac/available-commands.mdx delete mode 100644 tmp/docker-to-iac/before-you-start.mdx delete mode 100644 tmp/docker-to-iac/environment-variable-generation.mdx delete mode 100644 tmp/docker-to-iac/environment-variable.mdx delete mode 100644 tmp/docker-to-iac/example-of-a-new-parser.mdx delete mode 100644 tmp/docker-to-iac/limitations.mdx delete mode 100644 tmp/docker-to-iac/meta.json delete mode 100644 tmp/docker-to-iac/multi-file-configuration.mdx delete mode 100644 tmp/docker-to-iac/multi-services-support.mdx delete mode 100644 tmp/docker-to-iac/parser-explanation.mdx delete mode 100644 tmp/docker-to-iac/parser/aws-cloudformation.mdx delete mode 100644 tmp/docker-to-iac/parser/digitalocean.mdx delete mode 100644 tmp/docker-to-iac/parser/helm.mdx delete mode 100644 tmp/docker-to-iac/parser/index.mdx delete mode 100644 tmp/docker-to-iac/parser/render.com.mdx delete mode 100644 tmp/docker-to-iac/project-structure.mdx delete mode 100644 tmp/docker-to-iac/publishing-to-npm.mdx delete mode 100644 tmp/docker-to-iac/quickstart.mdx delete mode 100644 tmp/docker-to-iac/render-contributing-to-service-types.mdx delete mode 100644 tmp/docker-to-iac/service-connections.mdx delete mode 100644 tmp/docker-to-iac/supported-docker-compose-variables.mdx delete mode 100644 tmp/docker-to-iac/supported-registries.mdx delete mode 100644 tmp/docker-to-iac/testing.mdx diff --git a/app/sitemap.ts b/app/sitemap.ts new file mode 100644 index 0000000..526d33b --- /dev/null +++ b/app/sitemap.ts @@ -0,0 +1,30 @@ +import { MetadataRoute } from 'next'; +import { source } from '@/lib/source'; + +export const dynamic = 'force-static'; + +function getPages(tree: any): any[] { + const pages: any[] = []; + + function traverse(nodes: any[]) { + for (const node of nodes) { + if (node.type === 'page') { + pages.push(node); + } else if ('children' in node) { + traverse(node.children); + } + } + } + + traverse(tree.children); + return pages; +} + +export default function sitemap(): MetadataRoute.Sitemap { + const pages = getPages(source.pageTree).map((page) => ({ + url: new URL(page.url, 'https://docs.deploystack.io').toString(), + lastModified: page.lastModified, + })); + + return pages; +} diff --git a/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/application-logo-configuration.mdx b/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/application-logo-configuration.mdx deleted file mode 100644 index 5535809..0000000 --- a/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/application-logo-configuration.mdx +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: Application Logo Configuration -description: DeployStack logo configuration guide. Add a custom logo to your application with automatic WebP conversion, CDN delivery, and square format optimization. ---- - -# Application Logo Configuration - -Add a custom logo to make your application stand out in the DeployStack catalog. Your logo will be automatically optimized and served through our CDN for the best performance. - -## Adding Your Logo - -Configure your logo in `.deploystack/config.yml` - [DeployStack Configuration File Reference](/docs/deploystack/deploystack-config-file): - -```yaml -application: - logo: "https://example.com/path/to/logo.png" -``` - -## Logo Requirements - -### Supported Formats - -- PNG (`.png`) -- JPEG (`.jpg`, `.jpeg`) -- WebP (`.webp`) -- SVG (`.svg`) - -### Size Guidelines - -- Maximum input: 2 MB. -- Final output will be: - - Square format (1:1 aspect ratio) - - Maximum 500x500 pixels -- Input images will be: - - Resized if larger than 500px in either dimension - - Centered and cropped to maintain 1:1 aspect ratio - - Padded with transparency if needed to achieve square format - -## Image Processing - -When you configure a logo, DeployStack automatically: - -1. Downloads your original image -2. Optimizes it for web delivery -3. Converts it to WebP format -4. Stores it on our CDN -5. Serves it through our global CDN network - -### Optimization Process - -- Images larger than 500px in either dimension are resized -- Conversion to WebP for optimal compression -- Automatic quality optimization for web delivery - -## Notes - -- The logo configuration is optional -- You can update your logo at any time by modifying the config file -- Logo changes are processed only when made on the default branch -- Previous logo versions are automatically cleaned up diff --git a/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/deploystack-config-file.mdx b/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/deploystack-config-file.mdx deleted file mode 100644 index 78d2686..0000000 --- a/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/deploystack-config-file.mdx +++ /dev/null @@ -1,259 +0,0 @@ ---- -title: DeployStack Config File Reference -description: Documentation for DeployStack's config.yml schema. Customize your application's presentation with automatic IDE validation and flexible repository metadata overrides. ---- - -# DeployStack Configuration File Reference - -The `.deploystack/config.yml` file allows you to customize how your application appears in the DeployStack catalog and deployment interfaces. This configuration file supports automatic validation in popular IDEs through SchemaStore integration. - -## Configuration File Location - -Create a `config.yml` file in your repository's `.deploystack` directory: - -```bash -your-repository/ -├── .deploystack/ -│ ├── config.yml -│ └── docker-compose.yml (example, or docker-run.txt) -└── README.md -``` - -## Basic Configuration - -Here's a minimal configuration example: - -```yaml -application: - name: "My Application" - description: "A scalable web application with Redis caching" - logo: "https://example.com/path/to/logo.png" -``` - -## Configuration Options - -### Application Settings - -When you submit a repository to DeployStack, we automatically use: - -- Repository name as the application name -- Repository description as the application description - -You can override these values using the `config.yml` (only on your main branch) file: - -| Property | Type | Description | Constraints | -|----------|------|-------------|-------------| -| `mappings` | Array | Defines relationships between services for connection configuration | Required | -| `mappings[].fromService` | String | Service that needs to connect to another service | Required | -| `mappings[].toService` | String | Service being connected to | Required | -| `mappings[].environmentVariables` | Array of Strings | Environment variable names that reference the target service | Required | -| `mappings[].property` | String | Type of connection property to reference (e.g., 'connectionString', 'hostport') | Optional, defaults to 'hostport' | - -The override process follows this order: - -1. DeployStack first uses your repository name and description -2. If present, values in `.deploystack/config.yml` override the repository metadata - -### Branch Deployment Settings - -Before configuring multiple branch deployments, ensure you have installed the [DeployStack Repository Sync GitHub App](/docs/deploystack/github-application), as it's required for branch monitoring and template updates. - -You can configure multiple branch deployments using the `deployment.branches` section: - -| Property | Type | Description | Constraints | -|----------|------|-------------|-------------| -| `label` | String | Display name for the branch | Maximum 20 characters | -| `description` | String | Explain the branch's purpose or version | Maximum 100 characters | -| `active` | Boolean | Whether this branch is available for deployment | Optional, defaults to true | -| `priority` | Number | Order in which branches appear (lower numbers first) | Minimum value: 1 | -| `exclude_providers` | Array | Optional list of cloud providers to exclude from template generation for this branch | Values must be valid provider codes: "aws", "rnd", "dop" | - -The default branch always has `priority: 0` and appears first in the deployment options, regardless of other branch priorities. - -Example configuration for multiple branches: - -```yaml -application: - name: "My Application" - description: "A scalable web application" - -deployment: - branches: - v2: - label: "Beta (v2.x)" - description: "Preview of upcoming v2.x release" - priority: 1 - exclude_providers: - - "aws" # Exclude AWS CloudFormation for this branch - v3: - label: "Alpha (v3.x)" - description: "Early preview of v3.x" - priority: 2 -``` - -Each branch configuration allows you to: - -- Provide a user-friendly label for the version -- Include a description explaining the branch's purpose -- Control deployment availability with the `active` flag -- Set display order using `priority` - -When multiple branches are configured: - -- DeployStack generates separate deployment templates for each branch -- Users can choose which version to deploy -- The GitHub App monitors all configured branches for updates -- The default branch is always listed first with implicit `priority: 0` - -This is especially useful for projects that maintain multiple active versions simultaneously, such as stable and beta releases. - -The optional `exclude_providers` array allows you to specify which cloud providers should be excluded from template generation for particular branches. This is useful when certain features in a branch version may not be compatible with specific cloud providers. Valid provider codes are: - -Please check our [current supported provider list here](/docs/docker-to-iac/parser/index). - -For example, if your beta version uses features only supported in DigitalOcean, you might exclude the other providers: - -```yaml -v2-beta: - label: "Beta" - description: "Beta version with DigitalOcean-specific features" - exclude_providers: - - "aws" - - "rnd" -``` - -If no providers are excluded, templates will be generated for all supported cloud providers. - -### Service Connections - -You can configure service-to-service communication for multi-container applications using the `serviceConnections` property within each branch configuration. This feature is particularly useful for applications where services need to communicate with each other (e.g., web apps connecting to databases). - -| Property | Type | Description | Constraints | -|----------|------|-------------|-------------| -| `mappings` | Array | Defines relationships between services for connection configuration | Required | -| `mappings[].fromService` | String | Service that needs to connect to another service | Required | -| `mappings[].toService` | String | Service being connected to | Required | -| `mappings[].environmentVariables` | Array of Strings | Environment variable names that reference the target service | Required | - -Example configuration for service connections: - -```yaml -deployment: - branches: - main: - label: "Production" - description: "Production release" - serviceConnections: - mappings: - - fromService: "app" - toService: "db" - environmentVariables: - - "DATABASE_HOST" - - "DATABASE_URL" - property: "connectionString" - - fromService: "frontend" - toService: "api" - environmentVariables: - - "API_URL" - property: "hostport" -``` - -This configuration tells DeployStack how to properly configure communication between: - -- The "app" service and the "db" service through the DATABASE_HOST and DATABASE_URL environment variables -- The "frontend" service and the "api" service through the API_URL environment variable - -When templates are generated, DeployStack will transform these environment variables according to each cloud provider's specific service discovery mechanism: - -- For Render.com: Uses Blueprint's `fromService` syntax -- For DigitalOcean App Platform: Uses direct service name references - -For example, if your docker-compose.yml contains: - -```yaml -services: - app: - image: node:alpine - environment: - DATABASE_HOST: db - db: - image: mariadb:latest -``` - -The generated Render.com template would transform DATABASE_HOST to use their service discovery syntax: - -```yaml -services: - - name: app - # ...other configuration... - envVars: - - key: DATABASE_HOST - fromService: - name: db - type: pserv - property: hostport -``` - -## Schema Validation - -The configuration file is automatically validated against our JSON Schema when using supported IDEs (VS Code, IntelliJ, etc.). The schema is available at: - -```bash -https://cdnx.deploystack.io/schema/config.yml.json -``` - -## Notes - -- Changes to the configuration file are only processed when made on your repository's default branch -- The logo URL must be accessible and point to a valid image file -- All configuration properties are optional, but providing them improves your application's visibility in the DeployStack catalog - -## Usage Examples - -### Override Repository Metadata - -```yaml -application: - name: "Redis Cache Manager" # Overrides repository name - description: "A more detailed description that better explains your application" # Overrides repository description - logo: "https://example.com/logos/redis-manager.png" -``` - -### Configure Multiple Branch Deployments with Service Connections - -```yaml -deployment: - branches: - stable: - label: "Stable" - description: "Production-ready version" - priority: 1 - serviceConnections: - mappings: - - fromService: "web" - toService: "api" - environmentVariables: - - "API_ENDPOINT" - - fromService: "api" - toService: "db" - environmentVariables: - - "DB_HOST" - - "DB_CONNECTION" - - beta: - label: "Beta" - description: "Preview of upcoming features" - priority: 2 - exclude_providers: - - "aws" # Beta version not supported on AWS - serviceConnections: - mappings: - - fromService: "web" - toService: "api" - environmentVariables: - - "API_ENDPOINT" -``` - -### Minimal Configuration example for logo update - -Please visit our [Application Logo Configuration](/docs/deploystack/application-logo-configuration) page. diff --git a/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/deploystack-configuration-directory.mdx b/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/deploystack-configuration-directory.mdx deleted file mode 100644 index fd13942..0000000 --- a/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/deploystack-configuration-directory.mdx +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: .deploystack Directory Reference -description: Technical guide for setting up the .deploystack directory to manage Infrastructure as Code template generation and updates across your repository. ---- - -# .deploystack Directory Reference - -The `.deploystack` directory in your repository contains configuration files that DeployStack uses to generate and maintain your Infrastructure as Code templates. Creating this repo allows you to enable the [lifecycle of IaC](/docs/deploystack/iac-lifecycle). The deploystack configurations repo only makes sense if you also [install DeployStack GitHub app](/docs/deploystack/github-application). Otherwise, changes to DeployStack backend will not be recognized. - - -`.deploystack` directory is optional. You don't need to create it to submit your repository to deploystack.io. - - -## Directory Structure - -```bash -.deploystack/ -├── docker-compose.yml # Docker Compose configuration -├── docker-run.txt # Docker run command -├── env # Environment variables (optional) -``` - -## Configuration Files - -### DeployStack Configuration File - -Please read more at [DeployStack Configuration File Reference](/docs/deploystack/deploystack-config-file). - -### Docker Configuration - -Choose one of the following: - -- `docker-compose.yml` - Standard Docker Compose configuration -- `docker-run.txt` - Single Docker run command - -Example `docker-compose.yml`: - -```yaml -version: '3' -services: - web: - image: nginx:alpine - ports: - - "80:80" -``` - -Example `docker-run.txt`: - -```bash -docker run -d -p 80:80 nginx:alpine -``` - -### Environment Variables - -Please read more from our [environment variables](/docs/deploystack/docker-environment-variables) page. - -## Automatic Updates - -When the [DeployStack GitHub App](/docs/deploystack/github-application) is installed: - -1. Changes to specific (`docker-compose.yml` & `docker-run.txt`) file in `.deploystack/` trigger template updates -2. Updates only process when changes occur on the default branch -3. New templates are generated and stored in the [deploy-templates](https://github.com/deploystackio/deploy-templates) repository - -## Important Notes - -- The `.deploystack` directory is **optional** -- Without this directory, automatic template updates are **not** available -- You can add the directory and install the [DeployStack GitHub Sync App](/docs/deploystack/github-application) at any time -- [Environment variables](/docs/deploystack/docker-environment-variables) and [DeployStack config](/docs/deploystack/deploystack-config-file) are optional components -- Only one Docker configuration file should be used (either compose or run) diff --git a/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/docker-compose-requirements.mdx b/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/docker-compose-requirements.mdx deleted file mode 100644 index a54cf11..0000000 --- a/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/docker-compose-requirements.mdx +++ /dev/null @@ -1,102 +0,0 @@ ---- -title: Docker Compose Requirements -description: Technical requirements for using Docker Compose with DeployStack's cloud deployment automation. Includes supported properties, registry options, and validation rules. ---- - -# Docker Compose Requirements - -DeployStack is designed to work with Docker Compose files that meet specific requirements. This page outlines what we support and what limitations you need to be aware of. - -## Core Requirements - -Your `docker-compose.yml` file must: - -1. Use pre-built Docker images -2. Reference public images from Docker Hub or another registries -> check [Supported Registries](/docs/docker-to-iac/supported-registries) -3. Be a valid Docker Compose file (version 3 and above) - -Your docker-compose file does not necessarily have to be called `docker-compose.yml` and does not have to be located in the root directory. You can rename your docker compose file and store it in any sub directory. - -If your docker compose file is not located in the root directory and has not `docker-compose.yml` as the filename, you must submit the full path name to us by using the submit form [deploystack.io/submit](https://deploystack.io/submit) i.e.: `https://github.com/vuejs/vitepress/tree/main/deployment/docker-compose.yaml`. - -## Image Requirements - -### Must Use Pre-built Images - -Your services must specify the `image` property. For example: - -```yaml title="docker-compose.yml" -# ✅ Supported -services: - app: - image: nginx:latest - ports: - - "80:80" -``` - -### Build Instructions Not Supported - -We do not support services that use the `build` directive: - -```yaml title="docker-compose.yml" -# ❌ Not Supported -services: - app: - build: - context: ./build/app - dockerfile: Dockerfile -``` - -## Why These Requirements? - -The infrastructure templates we generate require specific, immutable container images to ensure consistent deployments. Cloud providers need to know exactly which image to pull, which is why we require pre-built images. - -## Supported Docker Compose Properties - -We currently support these Docker Compose properties -> please check [Supported Docker Compose Variables](/docs/docker-to-iac/supported-docker-compose-variables). - -### Kubernetes/Helm - -When generating Helm charts for Kubernetes: - -- Database services (MySQL, PostgreSQL, Redis, etc.) are converted to Bitnami Helm chart dependencies -- Environment variables are split between ConfigMaps (regular variables) and Secrets (sensitive data) -- Each service in your Docker Compose becomes a separate Deployment and Service -- Volume mounts are supported and configured as needed - -This allows for better security practices and easier management of your application on Kubernetes. - -## Multiple Services Support - -DeployStack can handle Docker Compose files with multiple services, but support varies by cloud provider: - -- Some providers support deploying all services at once -- Others will only deploy the first service in your compose file -- Kubernetes (Helm) supports multi-service deployments with each service becoming a separate Deployment - -Check the specific [Multi Services Support](/docs/docker-to-iac/multi-services-support) for details about multi-service support. - -## Working with Private Images - -Currently, DeployStack only supports public images from Docker Hub. If you need to use private images: - -1. Make your images public on Docker Hub or [other supported registries](/docs/docker-to-iac/supported-registries) -2. Update your docker-compose.yml to reference the public images -3. Submit your repository to DeployStack - -## Environment Variables - -Please read more from our [environment variables](/docs/deploystack/docker-environment-variables) page. - -## Validation - -When you submit your repository, we perform these checks: - -1. Valid Docker Compose syntax -2. Presence of required `image` property -3. Absence of unsupported features - -## Next Steps - -- See how [One-Click Deploy](/docs/deploystack/one-click-deploy) works -- Check the [Troubleshooting](/docs/deploystack/troubleshooting) guide if you run into issues diff --git a/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/getting-started.mdx b/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/getting-started.mdx deleted file mode 100644 index 19d10f4..0000000 --- a/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/getting-started.mdx +++ /dev/null @@ -1,194 +0,0 @@ ---- -title: Getting Started with DeployStack -description: Start deploying Docker applications across cloud providers with DeployStack. Step-by-step guide to generating infrastructure templates from Docker configurations. ---- - -# Getting Started with DeployStack - -DeployStack offers two distinct paths to transform your Docker projects into cloud-ready deployments: a Quick Start path for immediate results, and our Recommended path for enhanced control and automation. Let's explore both approaches in detail. - -## Understanding the Two Paths - -### 🚀 Quick Start Path - -The Quick Start path is designed for developers who want to immediately make their Docker projects deployable, with minimal setup required. This approach works with your existing repository structure. - -### Recommended Path - -The Recommended path provides additional features through a `.deploystack` configuration directory and GitHub app integration. This approach enables automatic updates, environment variable management, and project customization. - -## Quick Start Path: Detailed Guide - -### For Docker Compose Projects - -#### Requirements - -- A public GitHub repository -- A `docker-compose.yml` or `docker-compose.yaml` file in your repository's root directory -- Container images must be: - - Pre-built and available in supported registries - - Publicly accessible - - Referenced using the `image` directive - -#### Step-by-Step Process - -1. **Repository Preparation** - - Ensure your `docker-compose.yml` is in the root directory - - Verify all images are publicly accessible - - Check that your compose file uses supported configuration options - -2. **Submission** - - Visit [deploystack.io/submit](https://deploystack.io/submit) - - Enter your GitHub repository URL - - Our system automatically detects your compose file - - Review the detected configuration - -3. **Template Generation** - - Infrastructure templates are generated for each supported cloud provider - - Templates are stored in our public repository - - You receive deployment button code for your README.md - -### For Docker Run Commands - -#### Requirements - -- A public GitHub repository -- A valid Docker run command that includes: - - Image name and tag - - Port mappings (if required) - - Environment variables (if needed) - - Volume mounts (if necessary) - -#### Step-by-Step Process - -1. **Command Preparation** - - Ensure your Docker run command is complete and valid - - Verify all referenced images are publicly available - - Test the command locally if possible - -2. **Submission** - - Visit [deploystack.io/submit](https://deploystack.io/submit) - - Enter your GitHub repository URL - - Paste your Docker run command - - Review the parsed configuration - -3. **Template Generation** - - Infrastructure templates are generated automatically - - Templates are optimized for each cloud provider - - You receive deployment button code - -## Recommended Path: Comprehensive Setup - -### The `.deploystack` Directory Structure - -Create a `.deploystack` directory in your repository with these components: - -```bash -.deploystack/ -├── docker-compose.yml # Your Docker Compose configuration -├── docker-run.txt # Or your Docker run command -├── env # Environment variables (optional) -└── logo.webp # Your project logo (optional) -``` - -#### Component Details - -**Docker Configuration Files**: - -- `docker-compose.yml`: Your complete Docker Compose configuration -- `docker-run.txt`: Alternative to compose file, contains your Docker run command -- Only one of these files should be present - -For more configuration options please check our [.deploystack Directory Reference](/docs/deploystack/deploystack-configuration-directory). - -### GitHub App Integration - -The [DeployStack Repository Sync](https://github.com/apps/deploystack-repository-sync) app enables: - -1. **Automatic Updates** - - Monitors changes to your Docker configurations - - Updates templates when configurations change - - Ensures templates stay in sync with your project - -2. **Installation Steps** - - Visit the GitHub app installation page - - Select your repositories - - Configure access permissions - - Verify installation - -3. **Monitoring and Updates** - - Changes to `.deploystack` directory trigger updates - - Only default branch changes are processed - - Templates are automatically regenerated - -## Behind the Scenes: How It Works - -### The docker-to-iac Module - -Our open-source [docker-to-iac](https://github.com/deploystackio/docker-to-iac) module: - -- Parses your Docker configurations -- Handles multiple cloud provider translations -- Supports various infrastructure patterns -- Maintains provider-specific optimizations - -### Template Generation Process - -1. **Configuration Analysis** - - Docker configurations are parsed - - Dependencies are identified - -2. **Provider-Specific Translation** - - Templates generated for each provider - - Provider best practices applied - - Resource mappings optimized - -3. **Template Storage** - - Templates stored in [deploy-templates](https://github.com/deploystackio/deploy-templates) - - Version controlled for tracking - - Publicly accessible - -### Deployment Button Integration - -After template generation: - -1. Visit [deploystack.io/deploy-button](https://deploystack.io/deploy-button) -2. Select your preferred button style -3. Copy the generated code -4. Add to your README.md - -## Best Practices - -### Repository Organization - -- Keep Docker configurations clean and well-documented -- Use specific version tags for images -- Document environment variable requirements -- Include clear deployment instructions - -### Configuration Management - -- Use the `.deploystack` directory for better organization -- Keep environment variables separate -- Test configurations locally - -### Deployment Strategy - -- Start with the Quick Start path if needed -- Migrate to Recommended path for better control -- Use GitHub app for automatic updates - -## Troubleshooting Common Issues - -### Template Generation - -- Verify image accessibility -- Check Docker configuration syntax -- Ensure all required ports are exposed -- Validate environment variables - -## Need Additional Help? - -- Review our detailed [Troubleshooting Guide](/docs/deploystack/troubleshooting) -- Join our active [Discord Community](https://discord.gg/UjFWwByB) -- Submit issues on GitHub to our [Feedback repository](https://github.com/deploystackio/feedback) diff --git a/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/github-application.mdx b/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/github-application.mdx deleted file mode 100644 index 0bfd545..0000000 --- a/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/github-application.mdx +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: GitHub Application -description: Keep Docker configurations and deployment templates in sync with DeployStack's GitHub App. Updates templates automatically when files change. ---- - -# GitHub App Integration - -The DeployStack GitHub App ensures your Infrastructure as Code (IaC) templates remain synchronized with your Docker configurations. After submitting your repository to deploystack.io, install our GitHub App to enable automatic updates. - -## How It Works - -When you install the [DeployStack Repository Sync](https://github.com/apps/deploystack-repository-sync) app, it monitors specific files in your repository: - -- `.deploystack/` directory - [Contains your Docker configurations and assets](/docs/deploystack/deploystack-configuration-directory) -- `README.md` - For README.md updates - -When changes are detected in these files, the app automatically triggers an update of your IaC templates in our [deploy-templates](https://github.com/deploystackio/deploy-templates) repository. - - -Changes are only processed when they occur on your repository's **default branch**. Modifications in other branches will not trigger template, logo, config or any other updates. - - -## Installation - -1. Visit the [installation page](https://github.com/apps/deploystack-repository-sync/installations/new) -2. Select the repositories you want to monitor -3. Approve the requested permissions - -## Security & Permissions - -The app follows the principle of least privilege and requires only: - -- Read access to repository contents -- Read access to repository metadata - -These minimal permissions ensure the app can only: - -- Monitor changes to your Docker configurations -- Access basic repository information needed for template generation - -## What Gets Updated? - -When the app detects changes, it automatically updates: - -- Repository metadata in our catalog: - - Topics - - Repository Homepage - - Description -- IaC templates - - Depends on which technique (docker compose or docker run command) you choose, you can upload the `docker-compose.yml` or `docker-run.txt` in the `.deploystack` directory. Every time you update the files on your main branch (or additional branch), IaC templates will be updated automatically - [Automatic Updates](/docs/deploystack/deploystack-configuration-directory#automatic-updates). -- Environment variables - - To make it easier for a user to deploy IaC templates, it is recommended to work with environment variables. For this purpose, you can upload an `env` file and add your appropriate variables - [Environment Variables](/docs/deploystack/deploystack-configuration-directory#environment-variables). -- DeployStack Configuration -- Project / Applicaton Logo - - It is possible to upload your own logo to DeployStack catalog. To do this you need to upload a file to our directory `.deploystack`. Read more about it here: [Repository Logo](/docs/deploystack/deploystack-configuration-directory#repository-logo) - -## Managing the Integration - -You can manage or remove the integration at any time through your [GitHub Applications Settings](https://github.com/settings/installations). The app installation can be configured for specific repositories or your entire organization. - -## Next Steps - -After installing the app: - -1. Make changes to your Docker configurations in the `.deploystack` directory -2. Commit and push your changes -3. DeployStack will automatically update your deployment templates - -For details about the `.deploystack` directory structure, check our [.deploystack Directory Reference](/docs/deploystack/deploystack-configuration-directory). diff --git a/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/iac-lifecycle.mdx b/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/iac-lifecycle.mdx deleted file mode 100644 index e9e551f..0000000 --- a/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/iac-lifecycle.mdx +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: Infrastructure as Code Lifecycle -description: Guide to how DeployStack manages Infrastructure as Code template updates, including automatic synchronization, update triggers, and version control. ---- - -# Infrastructure as Code Lifecycle - -This guide explains how DeployStack manages and updates your Infrastructure as Code (IaC) templates throughout their lifecycle. - -## Template Generation Process - -### Initial Setup - -1. Create a `.deploystack` [configuration directory](/docs/deploystack/deploystack-configuration-directory) in your repository -2. Add your Docker configuration files: - - `docker-compose.yml` for Compose configurations - - `docker-run.txt` for Docker run commands -3. Submit your repository to [deploystack.io/submit](https://deploystack.io/submit) -4. Initial IaC templates are generated and stored in our [deploy-templates](https://github.com/deploystackio/deploy-templates) repository - -### Enabling Automatic Updates - -Install the [DeployStack Repository Sync](/docs/deploystack/github-application) GitHub App to keep your templates up to date when: - -- You modify Docker configurations in the `.deploystack` directory -- Cloud providers update their IaC specifications -- DeployStack improves its template generation - -![DeployStack IaC Lifecycle](../assets/images/deploystack/iac-lifecycle.webp) - -## Update Flow - -As the app GitHub repository owner, an update flow gives you control over the generation of Infrastructure as Code (IaC) templates. The flow allows you to regenerate IaC templates by changing, for example, the `.deploystack/docker-compose.yml` file. - -All IaC templates are stored in public and open-source repository: [https://github.com/deploystackio/deploy-templates](https://github.com/deploystackio/deploy-templates). - -### Prerequisites for activating the flow - -1. You have installed the [DeployStack GitHub app](/docs/deploystack/github-application). -2. You have created the `.deploystack/docker-run.txt` or `.deploystack/docker-compose.yml` file. - -The choice between `docker-run.txt` or `docker-compose.yml` depends on the submission process used to DeployStack. When submitting to DeployStack, you can choose two methods -> Docker Run or Docker Compose. - -### Example flow - -Let's say you want to change your image tag from "deploystack/awesomeapp:v1" to "deploystack/awesomeapp:v2-next". - -![DeployStack IaC Lifecycle](../assets/images/deploystack/deploystack-iac-flow-via-github-app.webp) - -1. To do this, you will edit the file `.deploy stack/docker-run.txt` and change your new docker tag -2. GitHub will send an event to the DeployStack backend with the change of the file `.deploy stack/docker-run.txt` because you have the DeployStack GitHub app installed. -3. DeployStack backend validates the change, and if everything test passes -4. By using [docker-to-iac module](https://github.com/deploystackio/docker-to-iac), DeployStack backend will generate the new IaC templates for your application and store them in our repository [https://github.com/deploystackio/deploy-templates](https://github.com/deploystackio/deploy-templates) - -## Update Triggers - -Your IaC templates are automatically updated in these scenarios: - -### Repository Changes - -When you modify files in your repository's default branch: - -- Changes to `docker-compose.yml` or `docker-run.txt` in `.deploystack` directory -- Updates to repository metadata - -### Provider Updates - -Templates are regenerated when: - -- Cloud providers modify their IaC specifications -- New provider features become available -- Provider API requirements change - -### System Updates - -DeployStack initiates template updates when: - -- The docker-to-iac module receives improvements -- New template optimizations are available -- Bug fixes are released - -## Template Versioning - -All template updates are version controlled in our [deploy-templates repository](https://github.com/deploystackio/deploy-templates), allowing you to: - -- Track template changes over time -- Review modification history -- Understand update triggers diff --git a/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/index.mdx b/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/index.mdx deleted file mode 100644 index 58ffd00..0000000 --- a/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/index.mdx +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: DeployStack Documentation -description: Official DeployStack documentation - Learn how to automate Docker Compose and run deployments across cloud providers. Clear guides and technical references for effective deployment automation. -menuTitle: DeployStack ---- - -# DeployStack - Open Source Cloud Deployment Guide - -DeployStack helps you deploy Docker Compose and Docker Run applications across different cloud providers by automatically generating Infrastructure as Code templates. Our documentation guides you through using DeployStack effectively. - -## Documentation Sections - -- [Getting Started](/docs/deploystack/getting-started.md) - Quick introduction and first steps -- [Docker Compose Requirements](/docs/deploystack/docker-compose-requirements.md) - Learn about supported configurations -- [One-Click Deploy](/docs/deploystack/one-click-deploy.md) - Learn about deployment automation -- [Troubleshooting](/docs/deploystack/troubleshooting.md) - Resolve common issues - -## Additional Resources - -- [Docker-to-IaC Module Documentation](/docs/docker-to-iac/index.md) -- [Join our Discord](https://discord.gg/UjFWwByB) -- [Visit DeployStack](https://deploystack.io) - diff --git a/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/multiple-branches.mdx b/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/multiple-branches.mdx deleted file mode 100644 index ddb2f35..0000000 --- a/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/multiple-branches.mdx +++ /dev/null @@ -1,150 +0,0 @@ ---- -title: Branch Strategy -description: Guide to implementing multi-branch deployment strategies with DeployStack, enabling version-specific deployments and automated template management. ---- - -# Branch Strategy - -DeployStack's branch strategy allows you to maintain and deploy multiple versions of your application simultaneously. This is particularly valuable when you're evolving your application while maintaining stable versions for production users. - -## The Multi-Version Journey - -### Starting Point: Default Branch - -Every repository starts with its default branch (typically `main` or `master`). This branch: - -- Always generates Infrastructure as Code templates -- Cannot be excluded from template generation -- Has implicit `priority: 0` in deployment options -- Can be changed through your repository settings - -When you change your default branch in GitHub: - -- DeployStack automatically detects the change - you need to install [DeployStack GitHub App](/docs/deploystack/github-application) -- Regenerates templates for the new default branch -- Updates all deployment buttons - -### Growing Your Application: Adding New Versions - -As your application evolves, you might want to: - -- Develop a new major version with breaking changes -- Maintain an LTS (Long Term Support) version -- Test new features with early adopters - -This is where branch configurations become powerful. You can maintain up to 5 active branches, each with: - -- Its own Docker configuration -- Separate environment variables -- Independent deployment options - -For example, when developing version 2 of your application: - -```yaml -deployment: - branches: - v2: - label: "Version 2 Beta" - description: "Next generation features" - priority: 1 -``` - -### Branch-Specific Configurations - -Each branch can have its own `.deploystack` directory with standard configuration files. First, create the directories on your default branch: - -```bash -# Default branch configuration - -your-repository/ -└── .deploystack/ - ├── config.yml - ├── docker-compose.yml - └── env -``` - -```bash -# v2 branch configuration - -your-repository/ -└── .deploystack/ - ├── config.yml - ├── docker-compose.yml - └── env -``` - -This structure allows you to: - -- Use different Docker configurations per branch -- Maintain separate environment variables -- Modify service configurations independently -- Keep each version's deployment parameters isolated - -Remember: The DeployStack GitHub App only monitors the standard filenames: check [.deploystack Directory Reference for more info](/docs/deploystack/deploystack-configuration-directory) - -## Real-World Example - -Let's say you're maintaining a web application: - -```yaml -application: - name: "MyWebApp" - description: "Modern web application stack" - -deployment: - branches: - v1-lts: - label: "v1 LTS" - description: "Stable v1.x release with long-term support" - priority: 1 - v2-beta: - label: "v2 Beta" - description: "New architecture with enhanced features" - priority: 2 - experimental: - label: "Edge" - description: "Latest experimental features" - priority: 3 -``` - -Each branch can have different Docker configurations: - -- `main` branch (v1.x stable): - - ```yaml - # docker-compose.yml - services: - web: - image: myapp:1.5 - ``` - -- `v2-beta` branch: - - ```yaml - # docker-compose.yml - services: - web: - image: myapp:2.0-beta - ``` - -## Benefits for Your Users - -This strategy allows your users to: - -- Choose the version that best fits their needs -- Test new versions while maintaining production deployments -- Safely transition between versions at their own pace -- Deploy LTS versions for stability -- Try experimental features in isolation - -## Important Notes - -- Maximum of 5 active branches supported -- Each branch can have unique Docker configurations -- Default branch can be changed (switch to another branch and make it default) but not excluded -- Branch configurations ([DeployStack config file](/docs/deploystack/deploystack-config-file)) must be in the default branch -- All branches are automatically monitored for changes -- Template regeneration happens automatically when: - - Branch content changes - - Default branch is changed - - Configuration is updated diff --git a/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/one-click-deploy.mdx b/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/one-click-deploy.mdx deleted file mode 100644 index 8cf961e..0000000 --- a/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/one-click-deploy.mdx +++ /dev/null @@ -1,157 +0,0 @@ ---- -title: One-Click Deploy -description: Technical docs for DeployStack's one-click deployment feature. Covers infrastructure template generation, cloud provider integration, and button configuration. ---- - -# One-Click Deploy - -DeployStack leverages existing deployment technologies from cloud providers to make application deployment as straightforward as possible. - -## How One-Click Deploy Works - -When you submit your repository to [deploystack.io/submit](https://deploystack.io/submit), we: - -1. Generate Infrastructure as Code (IaC) templates for [supported cloud providers](/docs/docker-to-iac/index) -2. Store these templates in our [deploy-templates repository](https://github.com/deploystackio/deploy-templates) -3. Create provider-specific deployment buttons for your README.md -> by [deploystack.io/deploy-button](https://deploystack.io/deploy-button) - -## Template Generation and Storage - -### Repository Structure - -All generated templates are stored in the [deploystackio/deploy-templates](https://github.com/deploystackio/deploy-templates) repository using this organization: - -- Each project gets its own subfolder and branch -- Naming convention: `-` (lowercase) -- Example: `microsoft-vscode` for Microsoft's VS Code repository - -### Branch Strategy - -We create a dedicated branch for each project to support one-click deployment functionality: - -- Branch name matches the subfolder name -- Contains all necessary IaC templates and configurations -- Enables direct integration with cloud provider deployment systems - -## Cloud Provider Integration - -### Current Providers - -We integrate with cloud providers' native deployment systems. For example: - -- **DigitalOcean**: Uses the "Deploy to DigitalOcean" functionality as documented in their [official guide](https://docs.digitalocean.com/products/app-platform/how-to/add-deploy-do-button/) -- **Kubernetes**: Generates Helm charts that can be deployed to any Kubernetes cluster -- Check [supported cloud providers](/docs/docker-to-iac/index) for full list - -### Provider-Specific Templates - -Each cloud provider may require specific template formats: - -- AWS CloudFormation templates -- DigitalOcean App Spec -- Render Blueprints -- And more based on provider requirements -- Kubernetes Helm charts with all necessary templates - -## Using Deploy Buttons - -After template generation, you'll receive HTML/Markdown code for deployment buttons by visitig the [deploystack.io/deploy-button](https://deploystack.io/deploy-button) page. - -There are two options you can chose from. The main difference is the deploy url. For the mode "Deploy via DeployStack" the deploy address points to the deploystack.io/deploy endpoint, where HTTP status code 302 redirects to the cloud provider one-click deploy endpoint. - -In the example below with render: - -```markdown -1. -> https://deploystack.io/deploy/microsoft-vscode?provider=rnd&language=rnd -2. -> HTTP 302 REDIRECT -3. -> https://render.com/deploy?repo=https://github.com/deploystackio/deploy-templates/tree/microsoft-vscode -``` - -### Deploy via DeployStack - -Link via deploystack deploy endpoint. - -- auto update on One-Click deploy links: if the provider's deploy url changes, we will update. -- future cloud provider support out of the box: The endpoint makes it easier for us to integrate with additional providers, which benefits your users. -- deploy statistics for your app: We collect anonymized statistics to show the number of deployments your application has had, similar to npm download statistics. - -#### Example Markdown Deploy via DeployStack - -- static deploy links: if the cloud provider changes the one-click deploy url, the functionality will also be broken. You have to update your `README.md` manually. -- no statistics collection possible: you will never know how many people use your project :) - -```markdown title="README.md" -## ⚡ One-Click Deploy - -| Cloud Provider | Deploy Button | -|---------------|---------------| -| Render | | -``` - -### Deploy Standalone - -Direct link to Cloud Provider to enable One-Click depoy. - -#### Example Markdown Deploy Standalone - -```markdown title="README.md" -## ⚡ One-Click Deploy - -| Cloud Provider | Deploy Button | -|---------------|---------------| -| Render | | -``` - -## License and Usage - -All generated templates are available under the MIT License: - -- Full license text available in the [deploy-templates repository](https://github.com/deploystackio/deploy-templates/blob/main/LICENSE) -- Free to use, modify, and distribute -- No warranty provided - -## Extending Provider Support - -Want to add support for another cloud provider? You can: - -1. Contribute to the [docker-to-iac module](https://github.com/deploystackio/docker-to-iac) -2. Add a new provider parser -3. Implement the necessary template generation logic - -Benefits of contributing: - -- All existing projects in our catalog automatically get templates for the new provider -- The open-source community benefits from broader deployment options -- Your provider becomes part of the one-click deployment ecosystem - -## Technical Implementation Details - -The one-click deployment process: - -1. User clicks deploy button -2. Cloud provider loads template from our repository's specific branch -3. Provider's deployment system processes the template -4. Application gets deployed according to specifications - -## Validation and Security - -For each deployment: - -- Templates are version controlled -- Source code is publicly accessible -- Infrastructure specifications are transparent -- No sensitive data is stored in templates - -## Future Enhancements - -We're continuously working to: - -- Add more cloud providers -- Improve template generation -- Enhance deployment options -- Support more complex configurations - -## Next Steps - -- Visit our [Discord community](https://discord.gg/UjFWwByB) for help -- Consider [contributing](https://github.com/deploystackio/docker-to-iac) to add more providers diff --git a/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/troubleshooting.mdx b/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/troubleshooting.mdx deleted file mode 100644 index 15bb2aa..0000000 --- a/docs-backup-2025-06-18T14-33-44-828Z/docs/deploystack/troubleshooting.mdx +++ /dev/null @@ -1,151 +0,0 @@ ---- -title: Troubleshooting DeployStack Issues -description: Technical solutions for common DeployStack deployment issues. Find answers to repository submission errors, license restrictions, and Docker Compose validation problems. ---- - -# Troubleshooting - -This guide helps you resolve common issues that might occur when submitting your repository to DeployStack. - -## Invalid GitHub Repository URL - -This error occurs when the submitted URL doesn't match the expected GitHub repository URL format. - -**Common causes:** - -- Missing 'github.com' in the URL -- Including query parameters - -**Solution:** -Use the standard GitHub repository URL format: - -```bash -https://github.com/username/repository -``` - -## Repository License Not Permitted - -We don't support certain licenses to protect both our users and our service. Here's what we currently don't support: - -| License Type | Reason for Restriction | -|-------------|------------------------| -| No License | Without a license, the code defaults to exclusive copyright, making it legally risky to use or deploy | -| Proprietary License | These licenses typically restrict redistribution and modification rights | -| Commons Clause | This addition to licenses restricts commercial use of the software | -| Shared Source | These licenses often include terms that limit deployment and distribution | -| Custom License | Custom licenses require individual legal review and may contain problematic terms | - -**Other Restrictions:** - -- Licenses containing "proprietary" terms -- Licenses with Commons Clause additions -- Licenses marked as "shared source" -- Any repository without clear license information - -**Solution:** - -Ensure your repository: - -- Uses a widely accepted open-source license (MIT, Apache, GPL, etc.) -- Has clear license information in the repository -- If you can, change your repository license to a supported one -- For special cases, whitelist requests can be submitted via [Discord](https://discord.gg/UjFWwByB) or Twitter DM - -## Invalid Base64 Encoding for Docker File - -This error occurs during our internal processing of your docker-compose file. - -**Common causes:** - -- File encoding issues -- Special characters in the file -- File corruption - -**Solution:** - -- Verify your docker-compose file uses UTF-8 encoding -- Remove any special characters -- Try re-creating the file if issues persist - -## Invalid Docker Compose File - -The submitted docker-compose file doesn't meet the required format or contains unsupported features. - -**Common causes:** - -- Invalid YAML syntax -- Unsupported Docker Compose version -- Missing required fields -- Using unsupported features - -**Solution:** - -- Validate your docker-compose file syntax -- Check our [Docker Compose Requirements](/docs/deploystack/docker-compose-requirements) page -- Ensure you're using supported features only - -## Error Converting Docker Compose to IaC - -This error occurs when our system cannot convert your docker-compose configuration to Infrastructure as Code templates. - -**Common causes:** - -- Unsupported service configurations -- Complex dependencies -- Resource definitions that can't be mapped to cloud provider services - -**Solution:** - -- Simplify your docker-compose configuration -- Review our [supported features documentation](/docs/docker-to-iac/supported-docker-compose-variables) -- Ensure all services use supported configurations - -## Error Listing Services from Docker Compose - -The system couldn't properly parse the services defined in your docker-compose file. - -**Common causes:** - -- Malformed service definitions -- Missing required service properties -- Invalid service configurations - -**Solution:** - -- Verify each service has the required `image` property -- Check service definitions follow the correct format -- Remove any unsupported service configurations - -## Internal Server Error - -This indicates an unexpected error in our validation process. - -**What it means:** - -- The error is on our end -- The issue isn't related to your repository or configuration -- We needs to investigate - -**What to do:** - -1. Try your submission again after a few minutes -2. If the error persists, join our [Discord community](https://discord.gg/UjFWwByB) -3. Report the issue with: - - Your repository URL - - Timestamp of the error - - Any error messages you received - -## General Troubleshooting Tips - -1. Validate your docker-compose file locally before submission -2. Ensure your repository meets all [requirements](/docs/deploystack/docker-compose-requirements) -3. Check that all services use supported configurations -4. Verify your repository is public and accessible - -## Need More Help? - -If you're still experiencing issues: - -- Join our [Discord community](https://discord.gg/UjFWwByB) -- Check our [Docker Compose Requirements](/docs/deploystack/docker-compose-requirements) -- Review [supported features](/docs/docker-to-iac/supported-docker-compose-variables) diff --git a/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/api.mdx b/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/api.mdx deleted file mode 100644 index 8aaff08..0000000 --- a/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/api.mdx +++ /dev/null @@ -1,790 +0,0 @@ ---- -title: docker-to-iac module API -description: Here's everything you need to know about our docker-to-iac module - from listing available cloud providers to converting your Docker setup into deployable code. ---- - -# docker-to-iac module API list - -In this page you will find all possible APIs for package docker-to-iac. - -## List all Parser - -To list all available parsers, please use the `listAllParsers()` method. - -### Example - -```typescript -import { listAllParsers } from '@deploystack/docker-to-iac'; - -const parsers = listAllParsers(); - -console.log('Available Parsers:'); -console.log(parsers); -``` - -#### Output - -```json -[ - { - providerWebsite: 'https://aws.amazon.com/cloudformation/', - providerName: 'Amazon Web Services', - providerNameAbbreviation: 'AWS', - languageOfficialDocs: 'https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html', - languageAbbreviation: 'CFN', - languageName: 'AWS CloudFormation', - defaultParserConfig: { files: [Array], cpu: 512, memory: '1GB' } - }, - { - providerWebsite: 'https://render.com/docs', - providerName: 'Render', - providerNameAbbreviation: 'RND', - languageOfficialDocs: 'https://docs.render.com/infrastructure-as-code', - languageAbbreviation: 'RND', - languageName: 'Render Blue Print', - defaultParserConfig: { - files: [Array], - subscriptionName: 'starter', - region: 'oregon', - diskSizeGB: 10 - } - }, - { - providerWebsite: 'https://www.digitalocean.com/', - providerName: 'DigitalOcean', - providerNameAbbreviation: 'DO', - languageOfficialDocs: 'https://docs.digitalocean.com/products/app-platform/', - languageAbbreviation: 'DOP', - languageName: 'DigitalOcean App Spec', - defaultParserConfig: { files: [Array], region: 'nyc', subscriptionName: 'basic-xxs' } - }, - { - providerWebsite: 'https://helm.sh/', - providerName: 'Kubernetes', - providerNameAbbreviation: 'K8S', - languageOfficialDocs: 'https://helm.sh/docs/', - languageAbbreviation: 'HELM', - languageName: 'Helm Chart', - defaultParserConfig: { - files: [Array], - cpu: '100m', - memory: '128Mi' - } - }, - { - providerWebsite: 'https://www.digitalocean.com/', - providerName: 'DigitalOcean', - providerNameAbbreviation: 'DO', - languageOfficialDocs: 'https://docs.digitalocean.com/products/app-platform/', - languageAbbreviation: 'DOP', - languageName: 'DigitalOcean App Spec', - defaultParserConfig: { files: [Array], region: 'nyc', subscriptionName: 'basic-xxs' } - } -] -``` - -**Note the files array**: that's because we have a [multi file strategy](/docs/docker-to-iac/multi-file-configuration). - -### Type - -```typescript -listAllParsers(): ParserInfo[] -``` - -## Get Parser Info - -If you want to extract the `defaultParserConfig` object from a parser, the `getParserInfo` method is the most suitable for this. - -### Example - -```typescript -import { getParserInfo } from '@deploystack/docker-to-iac'; - -const awsInfo = getParserInfo('CFN'); - -console.log('Available Parsers:'); -console.log(awsInfo); -``` - -#### Output - -```json -{ - providerWebsite: 'https://aws.amazon.com/cloudformation/', - providerName: 'Amazon Web Services', - providerNameAbbreviation: 'AWS', - languageOfficialDocs: 'https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html', - languageAbbreviation: 'CFN', - languageName: 'AWS CloudFormation', - defaultParserConfig: { - files: [ - { - path: 'aws-cloudformation.cf.yml', - templateFormat: 'yaml', - isMain: true, - description: 'AWS CloudFormation template' - } - ], - cpu: 512, - memory: '1GB' - } -} -``` - -### Type - -```typescript -getParserInfo(languageAbbreviation: string): ParserInfo -``` - -## Translate API - -Translate Docker configurations (both Docker run commands and docker-compose.yml files) into your chosen Infrastructure as Code language. - -### Function Signature - -```typescript -translate(input: string, options: { - source: 'run' | 'compose', - target: string, - templateFormat?: TemplateFormat, - environmentVariableGeneration?: EnvironmentVariableGenerationConfig; - environmentVariables?: Record; - persistenceKey?: string; - serviceConnections?: ServiceConnectionsConfig; -}): TranslationResult -``` - -Where `TranslationResult` has the structure: - -```typescript -interface TranslationResult { - files: { - [path: string]: FileOutput - }; - serviceConnections?: ResolvedServiceConnection[]; -} - -interface FileOutput { - content: string; - format: TemplateFormat; - isMain?: boolean; -} -``` - -### Examples - -#### Translating Docker Compose - -```javascript -import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs'; -import { join, dirname } from 'path'; -import { translate } from '@deploystack/docker-to-iac'; - -const dockerComposeContent = readFileSync('path/to/docker-compose.yml', 'utf8'); - -const result = translate(dockerComposeContent, { - source: 'compose', - target: 'CFN', - templateFormat: 'yaml' -}); - -// Access individual file contents -console.log(`Generated ${Object.keys(result.files).length} files:`); -Object.keys(result.files).forEach(path => { - console.log(`- ${path}`); -}); - -// Write files to disk preserving directory structure -Object.entries(result.files).forEach(([path, fileData]) => { - const fullPath = join('output', path); - const dir = dirname(fullPath); - - if (!existsSync(dir)) { - mkdirSync(dir, { recursive: true }); - } - - writeFileSync(fullPath, fileData.content); -}); -``` - -#### Translating Docker Run Command - -```javascript -import { translate } from '@deploystack/docker-to-iac'; -import { writeFileSync, mkdirSync, existsSync } from 'fs'; -import { join, dirname } from 'path'; - -const dockerRunCommand = 'docker run -d -p 8080:80 nginx:latest'; - -const result = translate(dockerRunCommand, { - source: 'run', - target: 'RND', - templateFormat: 'yaml' -}); - -console.log(result) - -// Access and save all generated files -Object.entries(result.files).forEach(([path, fileData]) => { - const fullPath = join('output', path); - const dir = dirname(fullPath); - - if (!existsSync(dir)) { - mkdirSync(dir, { recursive: true }); - } - - writeFileSync(fullPath, fileData.content); - console.log(`Created: ${path}`); -}); -``` - -#### Translating Docker Compose to Helm Chart - -```javascript -import { translate } from '@deploystack/docker-to-iac'; -import { writeFileSync, mkdirSync, existsSync } from 'fs'; -import { join, dirname } from 'path'; - -const dockerComposeContent = ` -version: '3' -services: - web: - image: nginx:latest - ports: - - "80:80" - db: - image: postgres:13 - environment: - POSTGRES_USER: myuser - POSTGRES_PASSWORD: mypassword - POSTGRES_DB: myapp -`; - -const result = translate(dockerComposeContent, { - source: 'compose', - target: 'HELM', - templateFormat: 'yaml' -}); - -// Access and save all generated files to create a complete Helm Chart -Object.entries(result.files).forEach(([path, fileData]) => { - const fullPath = join('helm-chart', path); - const dir = dirname(fullPath); - - if (!existsSync(dir)) { - mkdirSync(dir, { recursive: true }); - } - - writeFileSync(fullPath, fileData.content); - console.log(`Created: ${path}`); -}); -``` - -#### Example Output (Partial - Chart.yaml) - -```yaml -apiVersion: v2 -name: deploystack-app -description: A Helm chart for DeployStack application generated from Docker configuration -type: application -version: 0.1.0 -appVersion: 1.0.0 -maintainers: - - name: DeployStack - email: hello@deploystack.io -dependencies: - - name: db - repository: https://charts.bitnami.com/bitnami - version: ^12.0.0 - condition: dependencies.db.enabled -``` - -#### Configuring Service Connections - -```javascript -import { translate } from '@deploystack/docker-to-iac'; - -const dockerComposeContent = ` -version: "3" -services: - db: - image: mariadb:latest - environment: - - MYSQL_ROOT_PASSWORD=rootpass - app: - image: node:alpine - environment: - - DATABASE_HOST=db # This will be transformed -`; - -const result = translate(dockerComposeContent, { - source: 'compose', - target: 'DOP', // DigitalOcean App Platform - templateFormat: 'yaml', - serviceConnections: { - mappings: [ - { - fromService: 'app', // Service that needs to connect - toService: 'db', // Service to connect to - environmentVariables: [ // Env vars that reference the service - 'DATABASE_HOST' - ] - } - ] - } -}); - -// The result will include transformed service references: -console.log(result.serviceConnections); -``` - -### Example Output (AWS CloudFormation) - -```yaml -{ - files: { - 'render.yaml': { - content: 'services:\n' + - ' - name: default\n' + - ' type: web\n' + - ' env: docker\n' + - ' runtime: image\n' + - ' image:\n' + - ' url: docker.io/library/nginx:latest\n' + - ' startCommand: ""\n' + - ' plan: starter\n' + - ' region: oregon\n' + - ' envVars:\n' + - ' - key: PORT\n' + - ' value: "80"\n', - format: 'yaml', - isMain: true - } - } -} -Created: render.yaml -``` - -#### Translation with Environment Variable Generation - -```typescript -import { translate } from '@deploystack/docker-to-iac'; - -// Environment variable configuration -const envConfig = { - 'library/mariadb': { - versions: { - '*': { - environment: { - 'MYSQL_ROOT_PASSWORD': { - type: 'password', - length: 16 - }, - 'MYSQL_DATABASE': { - type: 'string', - length: 12, - pattern: 'lowercase' - } - } - } - } - } -}; - -const translatedConfig = translate(dockerComposeContent, { - source: 'compose', - target: 'CFN', - templateFormat: 'yaml', - environmentVariableGeneration: envConfig -}); -``` - -### Parameters - -#### `input: string` - -For Docker Compose: The contents of your docker-compose.yml file -For Docker run: The complete docker run command - -#### `options.source: 'run' | 'compose'` - -Specifies the input type: - -- `'run'` - For Docker run commands -- `'compose'` - For Docker Compose files - -#### `options.target: string` - -The IaC language to translate to. Currently supported targets: -Please see the sidebar on the left, section Parsers. - -#### `options.templateFormat?: TemplateFormat` - -Optional. The desired output format: - -- `'json'` - JavaScript Object Notation -- `'yaml'` - YAML format -- `'text'` - Plain text - -> [!IMPORTANT] -> Not all template formats are valid for every IaC language. For example, AWS CloudFormation only accepts YAML or JSON formats. Choose a format compatible with your target IaC language. - -#### `options.environmentVariableGeneration?: EnvironmentVariableGenerationConfig` - -Optional. Configuration for generating environment variable values. Structure: - -```typescript -type EnvironmentVariableGenerationConfig = { - [imageName: string]: { - versions: { - [version: string]: { - environment: { - [variableName: string]: { - type: 'password' | 'string' | 'number'; - length?: number; - pattern?: 'uppercase' | 'lowercase' | 'normal'; - min?: number; // For number type - max?: number; // For number type - } - } - } - } - } -} -``` - -Generation types: - -- `password`: Generates a secure random password -- `string`: Generates a random string -- `number`: Generates a random number within specified range - -Patterns (for string type): - -- `uppercase`: Only uppercase characters -- `lowercase`: Only lowercase characters -- `normal`: Mixed case with numbers - -Version matching: - -- Use exact versions (e.g., "10.5") -- Use "*" for all versions -- Use "latest" for latest version - -> [!IMPORTANT] -> Environment variables in your docker-compose.yml must use the `${VARIABLE_NAME}` syntax to be processed by the generator. - -#### `environmentVariables?: Record` - -Optional. The docker-to-iac module supports passing environment variables from `.env` files to your Infrastructure as Code templates. This feature allows you to manage configuration values separately from your Docker configurations and maintain consistency across deployments. - -```typescript -import { translate, parseEnvFile } from '@deploystack/docker-to-iac'; -import { readFileSync } from 'fs'; - -// Read and parse the .env file -const envContent = readFileSync('.env', 'utf-8'); -const envVariables = parseEnvFile(envContent); - -const result = translate(dockerConfig, { - source: 'run', // or 'compose' - target: 'RND', // or other supported targets - templateFormat: 'yaml', - environmentVariables: envVariables -}); -``` - -#### `options.persistenceKey?: string` - -Optional. The `persistenceKey` parameter allows you to maintain consistent variable values across multiple template generations. - -#### `options.serviceConnections?: ServiceConnectionsConfig` - -Optional. Configure service-to-service communications by defining which environment variables reference other services. - -```typescript -type ServiceConnectionsConfig = { - mappings: Array<{ - fromService: string; // Service that needs to connect - toService: string; // Service to connect to - environmentVariables: string[]; // Environment variables that reference the service - property?: string; // Connection property type (connectionString, hostport, etc.) - }> -}; -``` - -This option is currently supported by: - -- Render.com (RND): Uses Blueprint's `fromService` syntax -- DigitalOcean App Platform (DOP): Uses direct service names -- Kubernetes Helm Charts (HELM): Uses Kubernetes DNS service discovery - -Example: - -```javascript -serviceConnections: { - mappings: [ - { - fromService: 'frontend', - toService: 'api', - environmentVariables: ['API_URL'], - property: 'hostport' - }, - { - fromService: 'app', - toService: 'db', - environmentVariables: ['DATABASE_URL'], - property: 'connectionString' - } - ] -} -``` - -### Return Value - -Returns the translated Infrastructure as Code template and any resolved service connections: - -```typescript -{ - files: { - // Generated IaC template files with paths as keys - 'render.yaml': { content: '...', format: 'yaml', isMain: true } - }, - serviceConnections: [ - { - fromService: 'app', - toService: 'db', - variables: { - 'DATABASE_HOST': { - originalValue: 'db', - transformedValue: 'db' // Transformed as appropriate for the provider - } - } - } - ] -} -``` - -## List Services API - -Extract service configurations from either Docker run commands or docker-compose.yml files as structured JSON objects. - -### Function Signature - -```typescript -listServices(content: string, options: ListServicesOptions): { [key: string]: ServiceConfig } - -type ListServicesOptions = { - source: 'compose' | 'run'; - environmentVariableGeneration?: EnvironmentVariableGenerationConfig; - environmentVariables?: Record; - persistenceKey?: string; -}; -``` - -### Examples - -#### Listing Docker Compose Services with Environment Variables - -```javascript -import { readFileSync } from 'fs'; -import { listServices, parseEnvFile } from '@deploystack/docker-to-iac'; - -const dockerComposeContent = readFileSync('path/to/docker-compose.yml', 'utf8'); -const envContent = readFileSync('.env', 'utf-8'); -const envVariables = parseEnvFile(envContent); - -const services = listServices(dockerComposeContent, { - source: 'compose', - environmentVariables: envVariables -}); - -console.log(services); -``` - -##### Output with Environment Variables - -```json -{ - "db": { - "image": "mariadb:11.2", - "ports": [], - "command": "mariadbd --character-set-server=utf8mb4 --collation-server=utf8mb4_bin", - "restart": "unless-stopped", - "volumes": [{"host": "db", "container": "/var/lib/mysql"}], - "environment": { - "MYSQL_ROOT_PASSWORD": "mysecretpassword", - "MYSQL_USER": "myuser", - "MYSQL_PASSWORD": "mysecretpassword", - "MYSQL_DATABASE": "mydatabase" - } - } -} -``` - -#### Listing Docker Run Services - -```javascript -import { listServices } from '@deploystack/docker-to-iac'; - -const dockerRunCommand = 'docker run -d -p 8080:80 -e NODE_ENV=production nginx:latest'; - -const services = listServices(dockerRunCommand, { - source: 'run' -}); - -console.log(services); -``` - -##### Output - -```json -{ - "service": { - "image": "nginx:latest", - "ports": ["8080:80"], - "environment": { - "NODE_ENV": "production" - } - } -} -``` - -### Options - -#### `content: string` - -The input content to parse: - -- For Docker Compose: The contents of your docker-compose.yml file -- For Docker run: The complete docker run command - -#### `options.source: 'run' | 'compose'` - -Specifies the input type: - -- `'run'` - For Docker run commands -- `'compose'` - For Docker Compose files - -#### `options.environmentVariables?: Record` - -Optional. Environment variables from a `.env` file or other source. Used to substitute variables in the format `${VARIABLE_NAME}` in your Docker configuration. - -Example: - -```javascript -const envVariables = { - 'DB_PASSWORD': 'mysecretpassword', - 'DB_USERNAME': 'myuser', - 'DB_DATABASE': 'mydatabase' -}; -``` - -#### `options.environmentVariableGeneration?: EnvironmentVariableGenerationConfig` - -Optional. Configuration for automatically generating environment variable values. Structure: - -```typescript -type EnvironmentVariableGenerationConfig = { - [imageName: string]: { - versions: { - [version: string]: { - environment: { - [variableName: string]: { - type: 'password' | 'string' | 'number'; - length?: number; - pattern?: 'uppercase' | 'lowercase' | 'normal'; - min?: number; // For number type - max?: number; // For number type - } - } - } - } - } -} -``` - -Example: - -```javascript -const envGeneration = { - 'library/mariadb': { - versions: { - '*': { - environment: { - 'MYSQL_ROOT_PASSWORD': { - type: 'password', - length: 16 - }, - 'MYSQL_DATABASE': { - type: 'string', - length: 12, - pattern: 'lowercase' - } - } - } - } - } -}; -``` - -#### `options.persistenceKey?: string` - -Optional. A unique key to maintain consistent generated environment variables across multiple calls to `listServices` or `translate`. - -### Return Value - -Returns an object where: - -- Keys are service names -- Values are service configurations containing: - - `image`: Docker image name and tag - - `ports`: Array of port mappings - - `command`: Custom command (if specified) - - `restart`: Restart policy (if specified) - - `volumes`: Array of volume mappings (if specified) - - `environment`: Object of environment variables - -## Parse Environment File - -Parse a `.env` file content into a key-value object using the `parseEnvFile()` method. The method handles basic environment file syntax including comments and quoted values. - -### Example - -```typescript -import { parseEnvFile } from '@deploystack/docker-to-iac'; - -const envContent = ` -# Database settings -DB_HOST=localhost -DB_USER="admin" -DB_PASS='secretpass' -# Comment line -NUMBERS=123456 -QUOTED="value=with=equals" -`; - -const envVars = parseEnvFile(envContent); - -console.log('Parsed Environment Variables:'); -console.log(envVars); -``` - -#### Output - -```json -{ - "DB_HOST": "localhost", - "DB_USER": "admin", - "DB_PASS": "secretpass", - "NUMBERS": "123456", - "QUOTED": "value=with=equals" -} -``` - -### Type - -```typescript -parseEnvFile(content: string): Record -``` diff --git a/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/example-of-a-new-parser.mdx b/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/example-of-a-new-parser.mdx deleted file mode 100644 index 571f608..0000000 --- a/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/example-of-a-new-parser.mdx +++ /dev/null @@ -1,383 +0,0 @@ ---- -title: Example of a New Parser -description: Example code for adding a new parser to docker-to-iac, supporting both Docker run commands and Docker Compose files, with multi-file output and service connections ---- - -# Adding a New Parser - -> [!TIP] -> Thank you for your interest in collaborating! The docker-to-iac module will remain open source forever, helping simplify deployments across cloud providers without vendor lock-in. - -## Parser Implementation - -Create a new file inside `src/parsers/new-provider.ts`: - -```typescript -import { - BaseParser, - ParserInfo, - TemplateFormat, - ParserConfig, - FileOutput, - DockerImageInfo -} from './base-parser'; -import { ApplicationConfig } from '../types/container-config'; -import { parsePort } from '../utils/parsePort'; -import { parseCommand } from '../utils/parseCommand'; - -// Define default configuration for your parser -const defaultParserConfig: ParserConfig = { - files: [ - { - path: 'awesome-iac.yaml', - templateFormat: TemplateFormat.yaml, - isMain: true, - description: 'Main IaC configuration file' - }, - { - path: 'templates/resources.yaml', - templateFormat: TemplateFormat.yaml, - description: 'Additional resources configuration' - } - ], - cpu: 512, - memory: '1GB', - region: 'default-region', - subscriptionName: 'basic-tier' -}; - -// Optional: Add helper functions for your specific provider -function getNewProviderServiceType(imageInfo: DockerImageInfo): string { - // Logic to determine service type based on image - // Example: Check if it's a database, web service, etc. - return 'web-service'; // Default type -} - -// Optional: Add function to determine if an image is a managed service -function isNewProviderManagedService(imageInfo: DockerImageInfo): boolean { - // Check if this image should be handled as a managed service - const imageUrl = `${imageInfo.repository}:${imageInfo.tag || 'latest'}`; - return imageUrl.includes('postgres') || imageUrl.includes('redis'); -} - -class NewProviderParser extends BaseParser { - // Multi-file implementation - required by BaseParser - parseFiles(config: ApplicationConfig): { [path: string]: FileOutput } { - // Initialize result containers - const services: Array = []; - const managedServices: Array = []; - - // Track service mappings for managed services - const managedServiceMap = new Map(); - - // First pass: identify and register managed services - for (const [serviceName, serviceConfig] of Object.entries(config.services)) { - if (isNewProviderManagedService(serviceConfig.image)) { - // Create a managed service instead of a regular service - const managedName = `${serviceName}-managed`; - - // Track the mapping for service connections later - managedServiceMap.set(serviceName, managedName); - - // Add to managed services collection - managedServices.push({ - name: managedName, - type: getNewProviderServiceType(serviceConfig.image), - // Add provider-specific managed service properties - plan: defaultParserConfig.subscriptionName - }); - - // Skip further processing of this service - continue; - } - - // Regular services will be processed in the second pass - } - - // Second pass: process regular services with their connections - for (const [serviceName, serviceConfig] of Object.entries(config.services)) { - // Skip managed services already processed - if (managedServiceMap.has(serviceName)) { - continue; - } - - // Extract ports from service configuration - const ports = new Set(); - if (serviceConfig.ports) { - serviceConfig.ports.forEach(port => { - if (typeof port === 'object' && port !== null) { - ports.add(port.container); - } else { - const parsedPort = parsePort(port); - if (parsedPort) { - ports.add(parsedPort); - } - } - }); - } - - // Prepare basic service definition - const service: any = { - name: serviceName, - type: getNewProviderServiceType(serviceConfig.image), - image: serviceConfig.image, - command: parseCommand(serviceConfig.command), - environment: [] - }; - - // Add ports if available - if (ports.size > 0) { - service.ports = Array.from(ports); - } - - // Process service connections if available - if (config.serviceConnections) { - // First add regular environment variables - for (const [key, value] of Object.entries(serviceConfig.environment)) { - // Check if this variable is handled by service connections - const isHandledByConnection = config.serviceConnections.some(conn => - conn.fromService === serviceName && - Object.keys(conn.variables).includes(key) - ); - - if (!isHandledByConnection) { - // Regular environment variable - service.environment.push({ - key, - value: value.toString() - }); - } - } - - // Then add service connection variables with provider-specific syntax - for (const connection of config.serviceConnections) { - if (connection.fromService === serviceName) { - for (const [varName, varInfo] of Object.entries(connection.variables)) { - // Check if target is a managed service - if (managedServiceMap.has(connection.toService)) { - const targetName = managedServiceMap.get(connection.toService); - - // Use provider-specific reference syntax - service.environment.push({ - key: varName, - // Example: ${resources.MANAGED_SERVICE_NAME.CONNECTION_STRING} - value: `\${resources.${targetName}.${connection.property || 'connectionString'}}` - }); - } else { - // Regular service connection - service.environment.push({ - key: varName, - // Example: ${services.SERVICE_NAME.HOST_PORT} - value: `\${services.${connection.toService}.${connection.property || 'hostport'}}` - }); - } - } - } - } - } else { - // No service connections, just add all environment variables - service.environment = Object.entries(serviceConfig.environment).map(([key, value]) => ({ - key, - value: value.toString() - })); - } - - // Add service to collection - services.push(service); - } - - // Create main configuration - const mainConfig = { - version: '1.0', - provider: 'new-provider', - region: defaultParserConfig.region, - services - }; - - // Create resources configuration if we have managed services - const resourcesConfig = managedServices.length > 0 ? { - version: '1.0', - managedResources: managedServices - } : {}; - - // Return file mappings - the main file is required - const result: { [path: string]: FileOutput } = { - 'awesome-iac.yaml': { - content: this.formatFileContent(mainConfig, TemplateFormat.yaml), - format: TemplateFormat.yaml, - isMain: true - } - }; - - // Add resources file if we have managed services - if (managedServices.length > 0) { - result['templates/resources.yaml'] = { - content: this.formatFileContent(resourcesConfig, TemplateFormat.yaml), - format: TemplateFormat.yaml - }; - } - - return result; - } - - getInfo(): ParserInfo { - return { - providerWebsite: "https://newprovider.example.com", - providerName: "New Provider Cloud", - providerNameAbbreviation: "NP", - languageOfficialDocs: "https://docs.newprovider.example.com/iac", - languageAbbreviation: "NP", - languageName: "New Provider IaC", - defaultParserConfig - }; - } -} - -export default new NewProviderParser(); -``` - -## Configuration and Provider-Specific Logic - -### Service Type Detection - -Create a file for service type configuration in `src/config/newprovider/service-types.ts`: - -```typescript -interface NewProviderServiceTypeConfig { - type: string; - description: string; - versions: string; - isManaged?: boolean; -} - -interface NewProviderServiceTypesConfig { - serviceTypes: { - [key: string]: NewProviderServiceTypeConfig; - }; -} - -export const newProviderServiceTypesConfig: NewProviderServiceTypesConfig = { - serviceTypes: { - 'docker.io/library/mariadb': { - type: 'database', - description: 'MariaDB database service', - versions: '*' - }, - 'docker.io/library/postgres': { - type: 'database', - description: 'PostgreSQL database', - versions: '*', - isManaged: true - }, - 'docker.io/library/redis': { - type: 'cache', - description: 'Redis cache', - versions: '*', - isManaged: true - } - } -}; - -export function getNewProviderServiceType(imageString: string): string { - const baseImage = imageString.split(':')[0]; - return newProviderServiceTypesConfig.serviceTypes[baseImage]?.type || 'web'; -} - -export function isNewProviderManagedService(imageString: string): boolean { - const baseImage = imageString.split(':')[0]; - return !!newProviderServiceTypesConfig.serviceTypes[baseImage]?.isManaged; -} - -export type { NewProviderServiceTypeConfig, NewProviderServiceTypesConfig }; -``` - -### Service Connection Properties - -Update the service connection properties in `src/config/connection-properties.ts`: - -```typescript -export const servicePropertyMappings: Record = { - 'host': { - render: 'host', - digitalOcean: 'PRIVATE_DOMAIN', - newProvider: 'HOST' // Add your provider mapping - }, - 'port': { - render: 'port', - digitalOcean: 'PRIVATE_PORT', - newProvider: 'PORT' // Add your provider mapping - }, - 'hostport': { - render: 'hostport', - digitalOcean: 'PRIVATE_URL', - newProvider: 'ENDPOINT' // Add your provider mapping - } -}; - -export const databasePropertyMappings: Record = { - 'connectionString': { - render: 'connectionString', - digitalOcean: 'DATABASE_URL', - newProvider: 'CONNECTION_STRING' // Add your provider mapping - }, - // Add other mappings... -}; -``` - -## Adding Your Parser to the System - -Update `src/index.ts` to include your new parser: - -```typescript -// Import your new parser -import newProviderParserInstance from './parsers/new-provider'; - -// Add it to the parsers array -const parsers: BaseParser[] = [ - cloudFormationParserInstance, - renderParserInstance, - digitalOceanParserInstance, - newProviderParserInstance // Add your parser here -]; -``` - -## Testing - -Please read our guidelines for testing parsers in the [Testing section](/docs/docker-to-iac/testing). - -## New parser documentation - -Please update documentation in the [github.com/deploystackio/documentation](https://github.com/deploystackio/documentation) repository. - -## Checklist - -1. Support both input types: - - Docker run commands - - Docker Compose files - -2. Handle all service types: - - Regular web/application services - - Managed database services - - Cache services - -3. Handle resource mappings consistently: - - Container ports - - Environment variables - - Volume mounts - - Resource limits - - Service connections - -4. Process service connections correctly: - - Service-to-service references - - Service-to-managed-service references - - Use provider-specific connection syntax - -5. Provide clear error messages for: - - Unsupported features - - Invalid configurations - - Missing required fields - -6. Test edge cases: - - Multiple services with interdependencies - - Complex configurations with service connections - - Various image formats and service types diff --git a/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/index.mdx b/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/index.mdx deleted file mode 100644 index 09c73a0..0000000 --- a/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/index.mdx +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: Docker to Infrastructure 2 -description: Introduction to the node module docker-to-iac which allows you to transfer docker-compose into IaC templates -sidebar: docker-to-iac ---- - -# Docker to Infrastructure as Code Module - -Docker to IaC is a Node.js module that translates the `docker-compose.yml` file into various types of Infrastructure as Code (IaC) templates. The goal of the module is to make GitHub repositories with docker-compose more easily accessible to various cloud providers such as Amazon Web Services (AWS), Google Cloud, DigitalOcean, and so on. - -- GitHub repository: [github.com/deploystackio/docker-to-iac](https://github.com/deploystackio/docker-to-iac) -- npm registry: [npmjs.com/package/@deploystack/docker-to-iac](https://www.npmjs.com/package/@deploystack/docker-to-iac) - -## Motivation - -The project's motivation comes from the fact that there are so many cloud providers on the free market that it is impossible to know all of them. - -How the project came about: you found an open source project that you want to deploy to your cloud provider, you found the `docker-compose.yml` file, and now you have to extract all the variables by hand or write the Infrastructure as Code template yourself because your company IT policy at work does not allow deployments without IaC. 😀 - -That's how it can work! That's why we want to simplify deployments and minimize vendor lock-in. - -The focus of this project, however, is on container applications with `docker-compose.yml` or applications that can be containerized. - -## Highlights - -- List of all available parsers from module -- Support for docker-compose multiple services -- Setup for default settings for each cloud provider (i.e. CPU, RAM) -- Docker Compose services variables supported: - - image, command, port, environment - -## How does it work? - -The principle of the translation is straightforward. You need a `docker-compose.yml` file and the desired cloud provider where you want to deploy your container. The docker-to-iac module translates `docker-compose.yml` into an IaC or one-click deploy template. - -After the successful translation, you can deploy your containers to your cloud provider. - -## Limitations - -- Only pre-build container possible - -Please read more at the [limitations page](/docs/docker-to-iac/limitations.md) - -## Help wanted - -We would be very happy if you could help us to extend the docker-to-iac module to include additional cloud providers (parsers). All open source repositories listed on our [deploystack.io](https://deploystack.io) website would benefit from this. - -If the docker-to-iac module is extended with another parser, our backend automatically creates an update for the repository [github.com/deploystackio/deploy-templates](https://github.com/deploystackio/deploy-templates). Baiscally: if you add a new parser for the provider "foo-cloud" that has its own IaC language, or one-click deployment supported, all open source projects listed on deploystack.io will be extended with the IaC template for cloud provider "foo-cloud". - -Thank you! diff --git a/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/limitations.mdx b/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/limitations.mdx deleted file mode 100644 index 8ba65ba..0000000 --- a/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/limitations.mdx +++ /dev/null @@ -1,89 +0,0 @@ ---- -title: Limitations -description: Current limitations and constraints of the docker-to-iac module ---- - -# Limitations for docker-to-iac module - -## Registry Support - -The module currently supports Docker images from -> please check [Supported Registries for docker-to-iac module](/docs/docker-to-iac/supported-registries.md) - -## Docker Image Requirement - -The `docker-to-iac` module is designed to work exclusively with pre-built Docker images. This means that each service in your `docker-compose.yml` file must specify an `image` property. - -## Volume Support - -When working with volume mappings in your Docker configuration, be aware that volume support varies among cloud providers: - -- Some providers fully support multiple volume mappings -- Some providers only support the first volume mapping defined in your configuration -- Some providers support ephemeral files only, meaning no persistent volume storage is available -- Volume mapping implementation details can differ between providers - -Please check the specific provider's documentation to understand their volume mapping capabilities and limitations before deployment. - -For example, if your Docker configuration includes multiple volumes: - -```yaml -services: - app: - image: nginx:latest - volumes: - - ./config:/etc/nginx/conf.d - - ./logs:/var/log/nginx - - ./data:/usr/share/nginx/html -``` - -Depending on your chosen provider: - -- All volume mappings might be supported -- Only the first volume mapping (`./config:/etc/nginx/conf.d`) might be implemented -- No volumes might be supported, with only ephemeral storage available - -We recommend reviewing your target provider's documentation for detailed information about their volume support capabilities. - -### Build Instructions Not Supported - -The module does not support services that use the `build` directive. For example: - -```yaml [docker-compose.yml] -# ❌ Not Supported -services: - app: - build: - context: ./build/app - dockerfile: Dockerfile -``` - -Instead, you must use pre-built images: - -```yaml [docker-compose.yml] -# ✅ Supported -services: - app: - image: nginx:latest -``` - -#### Rationale - -This limitation exists because Infrastructure as Code (IaC) templates require specific, immutable container images to ensure consistent deployments. The infrastructure and the selection of cloud providers for this docker-to-iac module only allow pre-build container images. It is technically not possible to create a build with the preconfigured infrastructure. This is why the pre-build check was built in. This happens also because the scope of this module is only pre-build container. - -### Workaround - -If you need to use custom Docker images: - -Build your Docker images locally or in your CI/CD pipeline -Push them to a container registry (like Docker Hub, GitHub Container Registry, or AWS ECR) -Reference the pushed image in your docker-compose file using the image property - -For example: - -```yaml -services: - app: - image: ghcr.io/your-org/your-app:1.0.0 -``` - -This ensures that your IaC templates will have access to the exact same container image across all deployments. diff --git a/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/multi-services-support.mdx b/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/multi-services-support.mdx deleted file mode 100644 index 9645e4e..0000000 --- a/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/multi-services-support.mdx +++ /dev/null @@ -1,78 +0,0 @@ ---- -title: Multi-Service Support -description: Learn about multi-service deployment support - See how docker-to-iac handles multiple services in your container configurations. ---- - -# Multi-Service Support - -Multi-service support refers to the ability of a [parser](/docs/docker-to-iac/parser-explanation) to handle multiple container configurations when translating to Infrastructure as Code (IaC) templates. - -## Docker Run vs Docker Compose - -### Docker Run Commands - -By nature, Docker run commands define a single container. When you have multiple Docker run commands, each represents a separate service: - -```bash -# Service 1 -docker run -d -p 8080:80 nginx:alpine - -# Service 2 -docker run -d -p 6379:6379 redis:latest -``` - -### Docker Compose - -Docker Compose files can define multiple services within a single file: - -```yaml title="docker-compose.yml" -version: '3.2' - -services: - web: - image: nginx:alpine - ports: - - '8080:80' - - cache: - image: redis:latest - ports: - - '6379:6379' -``` - -## Parser Support for Multiple Services - -The ability to deploy multiple services simultaneously varies by cloud provider: - -### Full Multi-Service Support - -Some cloud providers can deploy multiple containers as part of a single deployment. In these cases, docker-to-iac will translate all services to the target IaC template: - -```javascript -// All services will be included in the translation -const translation = translate(dockerComposeContent, { - source: 'compose', - target: 'CFN' // AWS CloudFormation supports multiple services -}); -``` - -### Limited Service Support - -Some providers don't support deploying multiple containers simultaneously. For these providers: - -- For Docker Compose input: Only the first service from the file will be translated -- For Docker run commands: Each command must be translated separately - -```javascript -// Only the first service will be translated -const translation = translate(dockerComposeContent, { - source: 'compose', - target: 'RND' // Render.com currently supports single service deployments -}); -``` - -## Provider-Specific Behavior - -Before using a specific parser, check its multi-service capabilities in the [parser documentation](/docs/docker-to-iac/parser-explanation). This helps ensure your deployment strategy aligns with the provider's capabilities. - -Note that some providers may have different service limits or deployment patterns even when they support multiple services. Always consult the target provider's documentation for specific limitations. diff --git a/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/parser-explanation.mdx b/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/parser-explanation.mdx deleted file mode 100644 index ca69734..0000000 --- a/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/parser-explanation.mdx +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: Parser Explanation -description: Understand how parsers translate Docker run commands and Docker Compose files into cloud-specific Infrastructure as Code templates. Learn about provider configurations and language support. ---- - -# Parser Explanation in docker-to-iac - -A parser in docker-to-iac translates Docker configurations (either Docker run commands or docker-compose.yml files) into Infrastructure as Code (IaC) or One-Click Deploy templates. Each parser is designed to target a specific IaC language or cloud provider template format. - -## Input Types - -docker-to-iac can process two types of input: - -### Docker Run Commands - -```bash -docker run -d -p 8080:80 -e NODE_ENV=production nginx:latest -``` - -### Docker Compose Files - -```yaml -version: '3' -services: - web: - image: nginx:latest - ports: - - "8080:80" - environment: - NODE_ENV: production -``` - -## API - -For detailed API documentation, see the [parser API reference](/docs/docker-to-iac/api). - -## Default Parser Config - -Each parser includes default configurations specific to its target cloud provider. These defaults are necessary because providers have different compute specifications and limitations. - -Example: AWS Fargate has a minimum CPU allocation of 256, while DigitalOcean's [minimum setting is 1 vCPU](https://www.digitalocean.com/pricing/app-platform). The default parser config handles these provider-specific requirements. - -To retrieve default parser configurations through the API, see the [parser info documentation](/docs/docker-to-iac/api#get-parser-info). - -## Parser vs. Language - -The [ParserInfo type](https://github.com/deploystackio/docker-to-iac/blob/main/src/parsers/base-parser.ts) separates variables between `Provider` and `Language`. This separation exists because some cloud providers support multiple IaC languages. - -For example, AWS infrastructure can be defined using: - -- CloudFormation -- AWS CDK (for TypeScript, Python, etc.) -- Terraform - -When adding new parsers, consider whether multiple IaC languages are possible for your target provider. This affects how you name your parser file in `src/parsers/.ts`. It's why the [`translate()`](/docs/docker-to-iac/api#translate-api) method requires the target IaC language name (e.g., `CFN`) rather than the provider name (e.g., `AWS`). - -## Parser Implementation Notes - -Creating parsers for multi-cloud IaC tools like Terraform presents additional challenges. Terraform's [extensive provider ecosystem](https://registry.terraform.io/browse/providers) means a Terraform parser would need complex logic to handle various provider-specific implementations, making maintenance more difficult. - -In contrast, single-provider languages like AWS CloudFormation have a one-to-one relationship with their cloud provider, simplifying parser implementation and maintenance. diff --git a/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/parser/aws-cloudformation.mdx b/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/parser/aws-cloudformation.mdx deleted file mode 100644 index 30861bb..0000000 --- a/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/parser/aws-cloudformation.mdx +++ /dev/null @@ -1,97 +0,0 @@ ---- -title: AWS CloudFormation Parser -description: Translate docker docker-compose.yml file into AWS Cloud Formation with DeployStack ---- - -# AWS CloudFormation - Parser Full Documentation - -The parser for CloudFormation translates the `docker-compose.yml` file into CloudFormation. The parser logic can be found in GitHub inside [docker-to-iac repo](https://github.com/deploystackio/docker-to-iac/blob/main/src/parsers/aws-cloudformation.ts). - -## Parser language abbreviation for API - -- `languageAbbreviation`: `CFN`. - -## Prerequisite to deploy CloudFormation Template - -To deploy the CloudFormation template in your AWS account, you need a VPC with internet access. It should also be possible to create ENI ([AWS Elastic Network Interface](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-eni.html)) with public IP. The template uses __AWS Fargate__ without an Application Load Balancer to save costs. - -If you have the [default VPC](https://docs.aws.amazon.com/vpc/latest/userguide/default-vpc.html) in your AWS account that should be sufficient. - -## Architecture - -The architecture deploys an ECS service into a serverless [AWS Fargate](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/AWS_Fargate.html) cluster. An ECS service = service from `docker-compose.yml`. This means if you have two services in your docker-compose file, you will end up deploying two ECS services into your Fargate cluster. - -![AWS Architecture](../../assets/images/docker-to-iac/aws-fargate.drawio.png) - -The tasks within ECS services create an ENI that has a public IP address. Since we do not use an ALB ([Application Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/introduction.html)), you can only access the tasks via the port and the public IP address. - -When creating CloudFormation template, we decided not to use ALB to save costs. You can of course modify the CloudFormation template and add your ALB if needed. - -## Security Configuration - -### Container Security Groups - -For development and testing purposes, the template configures security groups with open TCP ports (0-65535). This configuration enables easy testing but is not recommended for production use. If you plan to use this template in production, modify the security group rules to restrict access to specific ports. - -```yaml -SecurityGroupIngress: - - IpProtocol: tcp - FromPort: 0 - ToPort: 65535 - CidrIp: 0.0.0.0/0 -``` - -### Container Root Filesystem - -To enable writes to ephemeral ECS storage, containers are configured with: - -```yaml -ReadonlyRootFilesystem: false -``` - -## Default output format - -- The default output format for this parser: `YAML`. - -## File Configuration - -The AWS CloudFormation parser generates a single consolidated template: - -- `aws-cloudformation.cf.yml` - The comprehensive CloudFormation template that defines all resources including ECS clusters, services, tasks, security groups, and IAM roles - -This single-file approach encapsulates the entire infrastructure definition in YAML format, making it ready for immediate deployment through the AWS CloudFormation console, CLI, or other AWS deployment tools. - -## Supported Docker Compose Variables - -The current version supports the following Docker Compose variables: - -For __services__: - -- image -- environment -- ports -- command - - -The supported variables that are not on this list are ignored. This means that they are not translated by the parser in Infrastructure as Code from `docker-compose.yml` or docker run command. - - -## Storage Support - -The current implementation uses ephemeral storage provided by AWS Fargate. Persistent storage solutions like EFS (Elastic File System) or EBS (Elastic Block Store) are not automatically configured due to complexity with multiple mount points and automated deployment requirements. - -For applications requiring persistent storage, consider: - -- Using external storage services (e.g., Amazon RDS for databases) -- Manually configuring EBS volumes -- Implementing a custom storage solution - -## Multi Services Support - -Multi `services` support for CloudFormation: __yes__ - -Please read more about [multi service support here](/docs/docker-to-iac/multi-services-support). - - -This CloudFormation template is designed for development and testing environments. For production deployments, review and adjust security groups, storage configuration, and other security settings according to your requirements. - diff --git a/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/parser/digitalocean.mdx b/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/parser/digitalocean.mdx deleted file mode 100644 index 5ea2624..0000000 --- a/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/parser/digitalocean.mdx +++ /dev/null @@ -1,189 +0,0 @@ ---- -title: DigitalOcean Parser -description: Translate docker docker-compose.yml file into DigitalOcean Infrastructure as Code with DeployStack ---- - -# DigitalOcean - Parser Full Documentation - -The parser for DigitalOcean translates the `docker-compose.yml` file into a DigitalOcean [App Spec](https://docs.digitalocean.com/products/app-platform/) template. The parser logic can be found in GitHub inside the [docker-to-iac repo](https://github.com/deploystackio/docker-to-iac/blob/main/src/parsers/digitalocean.ts). - -## Parser language abbreviation for API - -- `languageAbbreviation`: `DOP`. - -## Prerequisite to deploy DigitalOcean App Spec - -To use the DigitalOcean App Spec, you need a valid DigitalOcean account with access to the App Platform and sufficient credits. - -## Architecture - -The DigitalOcean App Spec will deploy your application entirely within App Platform using containerized services: - -### App Platform Services - -Services in your App Platform deployment fall into two categories: - -#### HTTP Services - -- Web-facing containers that serve HTTP traffic -- Automatically configured with HTTPS routing: - - First service gets the root path `/` - - Additional services receive paths based on their names, e.g., `/servicename` -- Ideal for web applications, APIs, and frontend services - -#### TCP Services - -- Database containers (MySQL, PostgreSQL, Redis, etc.) run as internal TCP services -- Configured with appropriate health checks and internal ports -- No external HTTP routing - only accessible by other services within the app -- Suitable for databases, caches, and message queues - -### Important Note About Databases - -While DigitalOcean offers managed database services, these cannot be automatically provisioned through one-click deployment. Instead, database containers (like MySQL, PostgreSQL, Redis) are deployed as TCP services within App Platform, allowing: - -- Immediate deployment without pre-existing infrastructure -- Internal communication between application components -- Simplified configuration for development and testing - -For production use cases where you need managed databases, you should: - -1. Manually create managed databases in your DigitalOcean account -2. Update the application configuration to use these managed instances - -After deployment, all services can be monitored and managed through your DigitalOcean App Platform dashboard. - -## Default output format - -- The default output format for this parser: `YAML`. - -## File Configuration - -The DigitalOcean parser generates a structured output with a specific file organization: - -- `.do/deploy.template.yaml` - The main App Platform specification file that defines all services, environment variables, and configuration options for deployment - -This single-file structure follows DigitalOcean's App Platform requirements, where all deployment configurations are contained within the standard location expected by the DigitalOcean CLI and deployment tools. - -## Supported Docker Compose Variables - -This parser supports the following Docker Compose variables for services: - -- image -- environment -- ports -- command - - -Supported variables not listed above will be ignored. They will not be translated into the Infrastructure as Code from `docker-compose.yml` or docker run command. - - -## Database Support - -DigitalOcean App Platform supports running database containers as internal TCP services. The parser automatically configures these services with appropriate health checks and port settings to ensure proper communication within your application. - -### Supported Databases - -The parser recognizes and configures the following database types: - -- MySQL/MariaDB (port 3306) -- PostgreSQL (port 5432) -- Redis (port 6379) -- MongoDB (port 27017) - -### Configuration Details - -Database service configurations are defined in `src/config/digitalocean/database-types.ts`. This configuration maps Docker images to their corresponding TCP port and health check settings. - -To add or modify database configurations: - -1. Locate the `database-types.ts` file -2. Edit the `digitalOceanDatabaseConfig` object -3. Define the mapping using this structure: - -```typescript -'docker.io/library/mariadb': { - engine: 'MYSQL', - description: 'MariaDB database service - maps to MySQL managed database due to compatibility', - portNumber: 3306 -} -``` - -### Example Transformation - -Original docker-compose.yml: - -```yaml -services: - db: - image: mariadb:11.2 - environment: - MYSQL_DATABASE: myapp - app: - image: nginx:alpine - ports: - - "80:80" -``` - -Generated App Spec: - -```yaml -spec: - services: - - name: db - image: - registry_type: DOCKER_HUB - registry: library - repository: mariadb - tag: "11.2" - health_check: - port: 3306 - internal_ports: - - 3306 - - name: app - image: - registry_type: DOCKER_HUB - registry: library - repository: nginx - tag: alpine - http_port: 80 - routes: - - path: / -``` - - -While running databases as App Platform services works well for development and testing, for production workloads consider using DigitalOcean's managed database offerings for better reliability and maintenance. - - -### Understanding TCP Services - -When a database image is detected, the parser: - -1. Configures the service without HTTP routing -2. Sets up appropriate internal ports for database communication -3. Adds health checks on the database's standard port -4. Ensures the service can communicate with other containers in your app - -This approach allows immediate deployment while maintaining proper isolation and communication between your application components. - -## Volume Support - -DigitalOcean App Platform supports ephemeral files only. This means: - -- No persistent volume storage is available -- Local filesystem is limited to 2GB -- Files are temporary and will be deleted after deployments or container replacements -- Each container instance has its own separate filesystem -- Changes to the filesystem are lost when instances are scaled or redeployed - - -Any `volumes` directives in your docker-compose.yml or docker run command will be ignored during the translation to App Platform specifications. - - -## Multi Services Support - -Multi `services` support for DigitalOcean: __yes__ - -DigitalOcean supports multiple services in a single App Spec file. - -Please read more about [multi service support here](/docs/docker-to-iac/multi-services-support). diff --git a/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/parser/helm.mdx b/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/parser/helm.mdx deleted file mode 100644 index b99c6ea..0000000 --- a/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/parser/helm.mdx +++ /dev/null @@ -1,210 +0,0 @@ ---- -title: Helm Parser Documentation -description: Translate Docker Compose files into Kubernetes Helm Charts with DeployStack docker-to-iac module ---- - -# Helm - Parser Full Documentation - -The parser for Helm translates Docker configurations into Kubernetes Helm Charts. The parser logic can be found in GitHub inside the [docker-to-iac repo](https://github.com/deploystackio/docker-to-iac/blob/main/src/parsers/helm.ts). - -## Parser language abbreviation for API - -- `languageAbbreviation`: `HELM`. - -## Prerequisite to deploy Helm Charts - -To deploy the generated Helm Charts, you need: - -- A Kubernetes cluster (local or cloud-based) -- Helm CLI installed (version 3.x recommended) -- Appropriate RBAC permissions to deploy resources in your target namespace - -### Kubernetes Resources - -The generated Helm Chart creates the following Kubernetes resources for each service in your Docker configuration: - -- **Deployments**: Container specifications, replica count, resource limits -- **Services**: Network access to your pods with appropriate ports -- **ConfigMaps**: Non-sensitive environment variables -- **Secrets**: Sensitive environment variables (passwords, tokens, etc.) - -### Database Support - -For database services, the parser leverages Helm's dependency management to incorporate official Bitnami charts: - -- **MySQL/MariaDB**: Uses Bitnami's MySQL/MariaDB chart -- **PostgreSQL**: Uses Bitnami's PostgreSQL chart -- **Redis**: Uses Bitnami's Redis chart -- **MongoDB**: Uses Bitnami's MongoDB chart - -Each database dependency is configured with appropriate defaults and includes persistent storage for data. - -## Default output format - -- The default output format for this parser: `YAML`. - -## File Configuration - -The Helm parser generates a complete Helm Chart directory structure: - -- `Chart.yaml` - The main chart definition with metadata and dependencies -- `values.yaml` - Configuration values that can be customized at deployment time -- `templates/` - Directory containing Kubernetes YAML templates: - - `deployment.yaml` - Deployment specifications for each service - - `service.yaml` - Service definitions for network access - - `configmap.yaml` - ConfigMap for non-sensitive environment variables - - `secret.yaml` - Secret for sensitive environment variables - - `_helpers.tpl` - Helper functions for template generation - - `NOTES.txt` - Usage instructions displayed after installation - -This multi-file approach follows the standard Helm Chart structure and allows for maximum flexibility when deploying to Kubernetes. - -## Supported Docker Compose Variables - -This parser supports the following Docker Compose variables: - -- `image` -- `environment` -- `ports` -- `command` -- `volumes` - - -The parser automatically detects sensitive environment variables (containing keywords like "password", "secret", "key", "token", or "auth") and places them in Kubernetes Secrets instead of ConfigMaps. - - -## Volume Support - -The parser supports Docker volume mappings by converting them to Kubernetes volume mounts: - -- Each volume is converted to a hostPath volume by default -- Volume names are sanitized to conform to Kubernetes naming conventions -- For production use, you should modify the generated templates to use more appropriate volume types (PersistentVolumeClaims, etc.) - -## Database Integration - -When a database service is detected (MySQL, PostgreSQL, Redis, MongoDB), the parser: - -1. Adds the corresponding Bitnami Helm chart as a dependency in `Chart.yaml` -2. Configures database settings in `values.yaml` -3. Maps environment variables to the expected format for the database chart -4. Sets up appropriate persistence configurations - -### Example Database Configuration - -For a PostgreSQL database in your Docker Compose file: - -```yaml -services: - db: - image: postgres:13 - environment: - POSTGRES_USER: myuser - POSTGRES_PASSWORD: mypassword - POSTGRES_DB: myapp -``` - -The parser will create: - -```yaml -# In Chart.yaml -dependencies: - - name: db - repository: https://charts.bitnami.com/bitnami - version: ^12.0.0 - condition: dependencies.db.enabled - -# In values.yaml -dependencies: - db: - enabled: true - auth: - postgres: - password: mypassword - database: myapp - username: myuser - password: mypassword - primary: - service: - ports: - postgresql: 5432 - persistence: - enabled: true - size: 8Gi -``` - -## Service Connections - -The parser supports service-to-service connections by leveraging Kubernetes DNS for service discovery. When a service refers to another service in an environment variable, the parser automatically configures the appropriate DNS references. - -For example, if your `app` service connects to a `db` service: - -```yaml -# Docker Compose -services: - app: - image: myapp - environment: - DATABASE_URL: postgresql://postgres:password@db:5432/mydb - - db: - image: postgres - environment: - POSTGRES_PASSWORD: password - POSTGRES_DB: mydb -``` - -The parser will create: - -```yaml -# In ConfigMap template -data: - DATABASE_URL: {{ include "deploystack.serviceReference" (dict "service" (index $.Values.services "db") "serviceKey" "db") }} -``` - -Which resolves to the Kubernetes DNS name: `db.{{ .Release.Namespace }}.svc.cluster.local:5432` - -## Multi Services Support - -Multi `services` support for Helm: **yes** - -Helm Charts are designed to handle multiple services and dependencies in a single deployment, making them ideal for complex applications. The parser transforms all services from your Docker Compose file into corresponding Kubernetes resources. - -Please read more about [multi service support here](/docs/docker-to-iac/multi-services-support). - -## Deployment Instructions - -To deploy the generated Helm Chart: - -1. Navigate to the directory containing the generated chart -2. Install dependencies: - - ```bash - helm dependency update - ``` - -3. Install the chart: - - ```bash - helm install my-release . - ``` - -4. For custom configurations: - - ```bash - helm install my-release . --set services.app.replicaCount=2 - ``` - -## Production Considerations - -For production deployments, consider the following modifications to the generated chart: - -1. Replace hostPath volumes with appropriate persistent volume claims -2. Adjust resource limits in `values.yaml` -3. Configure proper ingress settings for external access -4. Enable and configure horizontal pod autoscaling -5. Set up proper liveness and readiness probes - - -The generated Helm Chart is a starting point that you should review and customize to match your production requirements and security best practices. - diff --git a/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/parser/index.mdx b/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/parser/index.mdx deleted file mode 100644 index 87c45ce..0000000 --- a/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/parser/index.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Available parsers -description: View all available parsers in docker-to-iac for converting Docker Compose to cloud infrastructure templates. Supports major cloud providers. -menuTitle: Available parser ---- - -# Available parser list for module docker-to-iac - -Here you can find the list of available [parsers](/docs/docker-to-iac/parser-explanation.md): - -- [AWS CloudFormation](/docs/docker-to-iac/parser/aws-cloudformation.md) -- [Render.com](/docs/docker-to-iac/parser/render.com.md) -- [DigitalOcean](/docs/docker-to-iac/parser/digitalocean.md) -- [Helm (Kubernetes)](/docs/docker-to-iac/parser/helm.md) diff --git a/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/parser/render.com.mdx b/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/parser/render.com.mdx deleted file mode 100644 index 926c2fe..0000000 --- a/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/parser/render.com.mdx +++ /dev/null @@ -1,133 +0,0 @@ ---- -title: Render.com - Parser Full Documentation -description: Translate docker docker-compose.yml file into Render.com Infrastructure as Code with DeployStack ---- - -# Render.com - Parser Full Documentation - -The parser for Render.com translates the `docker-compose.yml` file into Render [BluePrint](https://render.com/docs/infrastructure-as-code). The parser logic can be found in GitHub inside [docker-to-iac repo](https://github.com/deploystackio/docker-to-iac/blob/main/src/parsers/render.ts). - -## Parser language abbreviation for API - -- `languageAbbreviation`: `RND`. - -## Prerequisite to deploy Render BluePrint - -There are no special requirements for using the Render.com blueprint. However, you need a valid render.com account with sufficient credits. - -## Architecture - -The BluePrint will create a render "web" service. - -Type = "[Web Service](https://render.com/docs/blueprint-spec#type)". - -Render dashboard will list all your web services. At the top, you can switch between Dashboard and BluePrints. - -![Render BluePrints](../../assets/images/docker-to-iac/render.com-dashboard-blueprints.png) - -After the BluePrint has been created through one-click deployment, the BluePrint will be visible in the BluePrint menu. - -In contrast to other cloud providers, Render.com's usability is very trivial. There is no VPC / VNet or anything else. After successful deployment, you can open your service via a URL. - -## Default output format - -- The default output format for this parser: `YAML`. - -## File Configuration - -The Render.com parser generates a single file output: - -- `render.yaml` - The main Blueprint configuration file that defines all services, environment variables, and disk configurations - -This straightforward single-file approach aligns with Render's Blueprint specification, which requires all service definitions to be contained within a single YAML file. The file is structured according to Render's requirements with services, environment variables, and disk configurations properly organized for immediate deployment. - -## Supported Docker Compose Variables - -The current version supports the following Docker Compose variables: - -For __services__: - -- image -- environment -- ports -- command - - -The supported variables that are not on this list are ignored. This means that they are not translated by the parser in Infrastructure as Code from `docker-compose.yml` or docker run command. - - -## Volume Support - -Render.com offers two types of storage options: - -### Default: Ephemeral Filesystem - -By default, Render services use an ephemeral filesystem where: - -- Changes to the filesystem are lost after deployments or restarts -- Each service instance has its own separate filesystem -- No data persists between deployments - -### Persistent Disk Option - -The parser supports adding persistent disk storage through the `volumes` directive: - -- Persistent disks are automatically configured with 10GB size -- Only one disk per service is supported -- Files are preserved across deployments and restarts -- Only filesystem changes under the disk's mount path are preserved - -Important limitations for persistent disks: - -- A disk can only be accessed by a single service instance -- Services with persistent disks cannot scale to multiple instances - -Read more here: [render.com/docs/disks](https://render.com/docs/disks) - -## Service Types - -The parser automatically determines the appropriate service type for each container in your Docker configuration: - -### Web Services (Default) - -By default, services are created as `type: web`, which is suitable for: - -- HTTP-based applications -- Frontend applications -- API servers -- Any service that needs to be publicly accessible - -### Private Services - -For databases and other TCP-based services, the parser automatically sets `type: pserv`. These services: - -- Are not publicly accessible -- Can communicate with other services over TCP -- Are ideal for databases and backend services - -Read more here: [render.com/docs/private-services](https://render.com/docs/private-services). - -The service type is determined based on the Docker image being used. For example: - -```yaml -services: - web: - image: nginx:latest - # Automatically set to type: web - - db: - image: mariadb:11.2 - # Automatically set to type: pserv -``` - -### Adding New Service Types - -If you're using a service that should be private but isn't automatically detected, please visit our [Render: Contributing to Render Service Types docs page](/docs/docker-to-iac/render-contributing-to-service-types). - -## Multi Services Support - -Multi `services` support for Render.com: __yes__ - -Since [multi services](https://render.com/docs/blueprint-spec#root-level-fields) feature is supported. - -Please read more about [multi service support here](/docs/docker-to-iac/multi-services-support). diff --git a/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/project-structure.mdx b/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/project-structure.mdx deleted file mode 100644 index 1c4126c..0000000 --- a/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/project-structure.mdx +++ /dev/null @@ -1,175 +0,0 @@ ---- -title: Project Structure -description: Directory structure and organization of the docker-to-iac module, including guidance for adding new parsers, source handlers, and tests. ---- - -# Project Structure of docker-to-iac Module - -The project follows standard npm module organization with a well-defined structure to handle both Docker run commands and Docker Compose files, supporting multiple output formats and comprehensive testing. - -## Directory Structure - -```bash -docker-to-iac/ -|-- src/ # Source code -| |-- index.ts # Main entry point -| |-- config/ # Provider-specific configurations -| | |-- connection-properties.ts -| | |-- digitalocean/ -| | | |-- database-types.ts -| | |-- render/ -| | |-- service-types.ts -| |-- parsers/ # IaC parsers for different cloud providers -| | |-- aws-cloudformation.ts -| | |-- base-parser.ts -| | |-- digitalocean.ts -| | |-- render.ts -| |-- sources/ # Input source handlers -| | |-- base.ts -| | |-- factory.ts -| | |-- compose/ # Docker Compose handling -| | | |-- index.ts -| | | |-- validate.ts -| | |-- run/ # Docker run command handling -| | |-- index.ts -| |-- types/ # TypeScript type definitions -| | |-- container-config.ts -| | |-- environment-config.ts -| | |-- service-connections.ts -| |-- utils/ # Helper utilities -| |-- constructImageString.ts -| |-- detectDatabaseEnvVars.ts -| |-- digitalOceanParserServiceName.ts -| |-- getDigitalOceanDatabaseType.ts -| |-- getImageUrl.ts -| |-- parseCommand.ts -| |-- parseDockerImage.ts -| |-- parseEnvFile.ts -| |-- processEnvironmentVariablesGeneration.ts -| |-- resolveEnvironmentValue.ts -| |-- (... and many more) -|-- test/ # Test files -| |-- e2e/ # End-to-end tests -| | |-- assertions/ # Test assertions -| | | |-- digitalocean.ts -| | | |-- do-port-assertions.ts -| | | |-- port-assertions.ts -| | | |-- render.ts -| | |-- docker-compose-files/ # Test Docker Compose files -| | |-- docker-run-files/ # Test Docker run commands -| | |-- output/ # Test output directory -| | |-- utils/ # Test utilities -| | |-- index.ts # Main E2E test executor -| | |-- test1.ts # Environment variables and volume mapping tests -| | |-- test2.ts # Port mapping tests -| | |-- test3.ts # Environment variable substitution tests -| | |-- test4.ts # Schema validation tests -| |-- unit/ # Unit tests -| | |-- config/ # Configuration tests -| | |-- parsers/ # Parser tests -| | |-- sources/ # Source handler tests -| | |-- utils/ # Utility function tests -| |-- test.ts # Main test entry point -|-- eslint.config.mjs # ESLint configuration -|-- tsconfig.json # TypeScript configuration -|-- vitest.config.ts # Vitest configuration -|-- package.json # Package configuration -|-- README.md # Project documentation -``` - -## Directory Purposes - -### Core Directories - -- `src/` - Source code for the module -- `test/` - Test files organized by test type (unit and end-to-end) -- `dist/` - Compiled output (generated during build) - -### Source Code Organization - -#### Config (`src/config/`) - -Contains provider-specific configurations: - -- `connection-properties.ts` - Cross-provider connection property mappings -- `digitalocean/` - DigitalOcean App Platform specific configurations - - `database-types.ts` - Database type mappings for DigitalOcean -- `render/` - Render.com specific configurations - - `service-types.ts` - Service type mappings for Render deployments - -#### Parsers (`src/parsers/`) - -Contains IaC-specific parsers for different cloud providers: - -- `base-parser.ts` - Base parser class that defines common functionality -- `aws-cloudformation.ts` - AWS CloudFormation parser -- `digitalocean.ts` - DigitalOcean App Platform parser -- `render.ts` - Render Blueprint parser -- ... additional parsers for other providers - -#### Source Handlers (`src/sources/`) - -Handles different input types: - -- `base.ts` - Base source handler interface -- `factory.ts` - Factory for creating appropriate source handlers -- `compose/` - Docker Compose file processing - - `index.ts` - Main Compose parser - - `validate.ts` - Compose file validation -- `run/` - Docker run command processing - - `index.ts` - Docker run command parser - -#### Types (`src/types/`) - -TypeScript type definitions: - -- `container-config.ts` - Container and service configuration types -- `environment-config.ts` - Environment variable configuration types -- `service-connections.ts` - Service connection configuration types - -#### Utilities (`src/utils/`) - -Helper functions for parsing and processing: - -- `constructImageString.ts` - Docker image string construction -- `detectDatabaseEnvVars.ts` - Database environment variable detection -- `digitalOceanParserServiceName.ts` - Name formatting for DigitalOcean -- `getDigitalOceanDatabaseType.ts` - Database type detection for DigitalOcean -- `parseDockerImage.ts` - Docker image parsing -- `parseEnvFile.ts` - Environment file parsing -- `resolveEnvironmentValue.ts` - Environment variable resolution -- And many more utility functions for specific operations - -### Test Organization - -#### End-to-End Tests (`test/e2e/`) - -Integration tests that validate the complete workflow: - -- `assertions/` - Validation functions for test output -- `docker-compose-files/` - Test Docker Compose files -- `docker-run-files/` - Test Docker run commands -- `output/` - Generated test outputs -- `utils/` - Test helper utilities -- `test1.ts` through `test4.ts` - Specific test scenarios: - 1. Environment variables and volume mapping - 2. Port mappings - 3. Environment variable substitution - 4. Schema validation - -#### Unit Tests (`test/unit/`) - -Tests for individual components: - -- `config/` - Tests for configuration modules -- `parsers/` - Tests for IaC parsers -- `sources/` - Tests for source handlers -- `utils/` - Tests for utility functions - -## Adding New Parser - -Please check our [Adding a New Parser](/docs/docker-to-iac/example-of-a-new-parser) documentation for detailed instructions on how to add a new parser to the project. This includes creating a new parser file, implementing the parsing logic, and ensuring compatibility with existing configurations. - -### Adding New Tests - -Please refer to the [Testing](/docs/docker-to-iac/testing) documentation for guidelines on adding new tests, including unit and end-to-end tests. diff --git a/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/quickstart.mdx b/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/quickstart.mdx deleted file mode 100644 index 67009de..0000000 --- a/docs-backup-2025-06-18T14-33-44-828Z/docs/docker-to-iac/quickstart.mdx +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: Quickstart Guide -description: Quickstart guide for using docker-to-iac to translate Docker run commands and Docker Compose files into infrastructure as code templates ---- - -# Quickstart Guide - -## Installation - -First, install the module and its dependencies: - -```bash -npm i @deploystack/docker-to-iac -``` - -## Usage Examples - -### Translating Docker Compose - -```javascript -import { translate } from '@deploystack/docker-to-iac'; -import { readFileSync, writeFileSync } from 'fs'; - -// Read Docker Compose file content -const dockerComposeContent = readFileSync('path/to/docker-compose.yml', 'utf8'); - -const translatedConfig = translate(dockerComposeContent, { - source: 'compose', - target: 'CFN', - templateFormat: 'yaml' -}); - -// Write the translated config to a file -writeFileSync('output-aws.yml', translatedConfig); -``` - -### Translating Docker Run Commands - -```javascript -import { translate } from '@deploystack/docker-to-iac'; -import { writeFileSync } from 'fs'; - -// Your docker run command -const dockerRunCommand = 'docker run -d -p 8080:80 -e NODE_ENV=production nginx:latest'; - -const translatedConfig = translate(dockerRunCommand, { - source: 'run', - target: 'CFN', - templateFormat: 'yaml' -}); - -// Write the translated config to a file -writeFileSync('output-aws.yml', translatedConfig); -``` - -### Translation Options - -When using the `translate` function, you can specify: - -- `source`: Either 'compose' or 'run' depending on your input -- `target`: The IaC language to translate to (e.g., 'CFN' for AWS CloudFormation) -- `templateFormat`: Output format - 'json', 'yaml', or 'text' - -For a complete list of supported parsers and formats, visit the [API documentation](/docs/docker-to-iac/api). diff --git a/docs-backup-2025-06-18T14-33-44-828Z/docs/index.mdx b/docs-backup-2025-06-18T14-33-44-828Z/docs/index.mdx deleted file mode 100644 index f89e880..0000000 --- a/docs-backup-2025-06-18T14-33-44-828Z/docs/index.mdx +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: DeployStack Documentation -description: Welcome to DeployStack documentation. Learn how to automate Docker Compose deployments across cloud providers with Infrastructure as Code templates and one-click deployments. -icon: CircleHelp ---- - -import { CloudUpload, Terminal, FileText, Container, BookOpenText, MessageCircleHeart } from 'lucide-react'; - -# DeployStack Documentation - -DeployStack converts your **Docker configurations** into **Infrastructure as Code** (IaC) templates for multiple cloud providers. Whether you have a docker-compose.yml file or docker run commands, it generates the necessary AWS CloudFormation, Render.com Blueprint, DigitalOcean specifications, or Kubernetes Helm charts for example. This lets you and your users deploy the same application consistently across different cloud platforms using their native deployment mechanisms, **without needing to manually create** each provider's infrastructure. - -## Get Started - -DeployStack simplifies cloud deployment through three key steps: configure your Docker setup, translate docker compose or run command to IaC templates, and enable one-click deployment for your users. Start by understanding the core concepts and how to integrate DeployStack with your repository. - -### Core Concepts - - -} title="Quickstart" href="/docs/deploystack/getting-started"> -Start with our Getting Started Guide to understand the basics of DeployStack. - -} title="One-Click Deploy" href="/docs/deploystack/one-click-deploy"> -Learn how to enable One-Click Deploy buttons for your repository. - -} title="Configuration" href="/docs/deploystack/deploystack-configuration-directory"> -Configuration file placed to your repository, telling Zerops how to build and start your app. - - - -### Supported Cloud Providers - -DeployStack generates infrastructure templates for major cloud providers, each optimized for their specific deployment patterns. AWS CloudFormation templates use Fargate for containerized workloads, DigitalOcean leverages App Platform, and Render.com implements Blueprints for smooth deployment. While translating your docker command to Infrastructure as Code by using [docker-to-iac](/docs/docker-to-iac/index.md) module, you can choose your target provider. - - - -AWS - - -DigitalOcean - - -Render.com - - -Helm - - - -### DeployStack Ecosystem - -DeployStack consists of several integrated components that work together to enable consistent Docker to cloud deployment. Each repository serves a specific purpose in the ecosystem: - - -} title="docker-to-iac" href="https://github.com/deploystackio/docker-to-iac"> -The core Node.js module that handles Docker configuration translation to Infrastructure as Code templates - -} title="documentation" href="https://github.com/deploystackio/documentation"> -Central repository for all DeployStack documentation and guides - -} title="deploy-templates" href="https://github.com/deploystackio/deploy-templates"> -Houses all generated Infrastructure as Code templates for supported repositories - -} title="feedback" href="https://github.com/deploystackio/feedback"> -Public repository for feature requests, bug reports, and roadmap discussions - - - -## Contributing to DeployStack docker-to-iac module - -DeployStack is open source and we welcome contributions. Here's how you can help: - -- Add support for new cloud providers -- Improve existing Infrastructure as Code templates -- Enhance documentation -- Report issues and suggest improvements - -Visit our [GitHub repository](https://github.com/deploystackio/docker-to-iac) to get started. - -## Community and Support - -- Join our [Discord community](https://discord.gg/UjFWwByB) -- Check our [troubleshooting guide](/docs/deploystack/troubleshooting.md) diff --git a/lib/seo-utils.ts b/lib/seo-utils.ts index 18232ca..afaa1b6 100644 --- a/lib/seo-utils.ts +++ b/lib/seo-utils.ts @@ -23,11 +23,11 @@ export function getSchemaOrgData(pageData: PageSEOData) { ] }, { - "@id": "https://deploystack.io/docs/#website", + "@id": "https://deploystack.io/#website", "@type": "WebSite", "inLanguage": "en", "name": "DeployStack Documentation", - "url": "https://deploystack.io/docs/", + "url": "https://deploystack.io/", "publisher": { "@id": "https://deploystack.io/#identity" }, @@ -119,7 +119,7 @@ export function generatePageMetadata(pageData: PageSEOData): Metadata { } export function getCanonicalUrl(slug: string): string { - const baseUrl = 'https://deploystack.io/docs'; + const baseUrl = 'https://docs.deploystack.io'; if (slug === '' || slug === '/') { return baseUrl; diff --git a/tmp/docker-to-iac/api.mdx b/tmp/docker-to-iac/api.mdx deleted file mode 100644 index 9469835..0000000 --- a/tmp/docker-to-iac/api.mdx +++ /dev/null @@ -1,791 +0,0 @@ ---- -title: docker-to-iac module API -description: Here's everything you need to know about our docker-to-iac module - from listing available cloud providers to converting your Docker setup into deployable code. -menuTitle: API ---- - -# docker-to-iac module API list - -In this page you will find all possible APIs for package docker-to-iac. - -## List all Parser - -To list all available parsers, please use the `listAllParsers()` method. - -### Example - -```typescript -import { listAllParsers } from '@deploystack/docker-to-iac'; - -const parsers = listAllParsers(); - -console.log('Available Parsers:'); -console.log(parsers); -``` - -#### Output - -```json -[ - { - providerWebsite: 'https://aws.amazon.com/cloudformation/', - providerName: 'Amazon Web Services', - providerNameAbbreviation: 'AWS', - languageOfficialDocs: 'https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html', - languageAbbreviation: 'CFN', - languageName: 'AWS CloudFormation', - defaultParserConfig: { files: [Array], cpu: 512, memory: '1GB' } - }, - { - providerWebsite: 'https://render.com/docs', - providerName: 'Render', - providerNameAbbreviation: 'RND', - languageOfficialDocs: 'https://docs.render.com/infrastructure-as-code', - languageAbbreviation: 'RND', - languageName: 'Render Blue Print', - defaultParserConfig: { - files: [Array], - subscriptionName: 'starter', - region: 'oregon', - diskSizeGB: 10 - } - }, - { - providerWebsite: 'https://www.digitalocean.com/', - providerName: 'DigitalOcean', - providerNameAbbreviation: 'DO', - languageOfficialDocs: 'https://docs.digitalocean.com/products/app-platform/', - languageAbbreviation: 'DOP', - languageName: 'DigitalOcean App Spec', - defaultParserConfig: { files: [Array], region: 'nyc', subscriptionName: 'basic-xxs' } - }, - { - providerWebsite: 'https://helm.sh/', - providerName: 'Kubernetes', - providerNameAbbreviation: 'K8S', - languageOfficialDocs: 'https://helm.sh/docs/', - languageAbbreviation: 'HELM', - languageName: 'Helm Chart', - defaultParserConfig: { - files: [Array], - cpu: '100m', - memory: '128Mi' - } - }, - { - providerWebsite: 'https://www.digitalocean.com/', - providerName: 'DigitalOcean', - providerNameAbbreviation: 'DO', - languageOfficialDocs: 'https://docs.digitalocean.com/products/app-platform/', - languageAbbreviation: 'DOP', - languageName: 'DigitalOcean App Spec', - defaultParserConfig: { files: [Array], region: 'nyc', subscriptionName: 'basic-xxs' } - } -] -``` - -**Note the files array**: that's because we have a [multi file strategy](/docs/docker-to-iac/multi-file-configuration.md). - -### Type - -```typescript -listAllParsers(): ParserInfo[] -``` - -## Get Parser Info - -If you want to extract the `defaultParserConfig` object from a parser, the `getParserInfo` method is the most suitable for this. - -### Example - -```typescript -import { getParserInfo } from '@deploystack/docker-to-iac'; - -const awsInfo = getParserInfo('CFN'); - -console.log('Available Parsers:'); -console.log(awsInfo); -``` - -#### Output - -```json -{ - providerWebsite: 'https://aws.amazon.com/cloudformation/', - providerName: 'Amazon Web Services', - providerNameAbbreviation: 'AWS', - languageOfficialDocs: 'https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html', - languageAbbreviation: 'CFN', - languageName: 'AWS CloudFormation', - defaultParserConfig: { - files: [ - { - path: 'aws-cloudformation.cf.yml', - templateFormat: 'yaml', - isMain: true, - description: 'AWS CloudFormation template' - } - ], - cpu: 512, - memory: '1GB' - } -} -``` - -### Type - -```typescript -getParserInfo(languageAbbreviation: string): ParserInfo -``` - -## Translate API - -Translate Docker configurations (both Docker run commands and docker-compose.yml files) into your chosen Infrastructure as Code language. - -### Function Signature - -```typescript -translate(input: string, options: { - source: 'run' | 'compose', - target: string, - templateFormat?: TemplateFormat, - environmentVariableGeneration?: EnvironmentVariableGenerationConfig; - environmentVariables?: Record; - persistenceKey?: string; - serviceConnections?: ServiceConnectionsConfig; -}): TranslationResult -``` - -Where `TranslationResult` has the structure: - -```typescript -interface TranslationResult { - files: { - [path: string]: FileOutput - }; - serviceConnections?: ResolvedServiceConnection[]; -} - -interface FileOutput { - content: string; - format: TemplateFormat; - isMain?: boolean; -} -``` - -### Examples - -#### Translating Docker Compose - -```javascript -import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs'; -import { join, dirname } from 'path'; -import { translate } from '@deploystack/docker-to-iac'; - -const dockerComposeContent = readFileSync('path/to/docker-compose.yml', 'utf8'); - -const result = translate(dockerComposeContent, { - source: 'compose', - target: 'CFN', - templateFormat: 'yaml' -}); - -// Access individual file contents -console.log(`Generated ${Object.keys(result.files).length} files:`); -Object.keys(result.files).forEach(path => { - console.log(`- ${path}`); -}); - -// Write files to disk preserving directory structure -Object.entries(result.files).forEach(([path, fileData]) => { - const fullPath = join('output', path); - const dir = dirname(fullPath); - - if (!existsSync(dir)) { - mkdirSync(dir, { recursive: true }); - } - - writeFileSync(fullPath, fileData.content); -}); -``` - -#### Translating Docker Run Command - -```javascript -import { translate } from '@deploystack/docker-to-iac'; -import { writeFileSync, mkdirSync, existsSync } from 'fs'; -import { join, dirname } from 'path'; - -const dockerRunCommand = 'docker run -d -p 8080:80 nginx:latest'; - -const result = translate(dockerRunCommand, { - source: 'run', - target: 'RND', - templateFormat: 'yaml' -}); - -console.log(result) - -// Access and save all generated files -Object.entries(result.files).forEach(([path, fileData]) => { - const fullPath = join('output', path); - const dir = dirname(fullPath); - - if (!existsSync(dir)) { - mkdirSync(dir, { recursive: true }); - } - - writeFileSync(fullPath, fileData.content); - console.log(`Created: ${path}`); -}); -``` - -#### Translating Docker Compose to Helm Chart - -```javascript -import { translate } from '@deploystack/docker-to-iac'; -import { writeFileSync, mkdirSync, existsSync } from 'fs'; -import { join, dirname } from 'path'; - -const dockerComposeContent = ` -version: '3' -services: - web: - image: nginx:latest - ports: - - "80:80" - db: - image: postgres:13 - environment: - POSTGRES_USER: myuser - POSTGRES_PASSWORD: mypassword - POSTGRES_DB: myapp -`; - -const result = translate(dockerComposeContent, { - source: 'compose', - target: 'HELM', - templateFormat: 'yaml' -}); - -// Access and save all generated files to create a complete Helm Chart -Object.entries(result.files).forEach(([path, fileData]) => { - const fullPath = join('helm-chart', path); - const dir = dirname(fullPath); - - if (!existsSync(dir)) { - mkdirSync(dir, { recursive: true }); - } - - writeFileSync(fullPath, fileData.content); - console.log(`Created: ${path}`); -}); -``` - -#### Example Output (Partial - Chart.yaml) - -```yaml -apiVersion: v2 -name: deploystack-app -description: A Helm chart for DeployStack application generated from Docker configuration -type: application -version: 0.1.0 -appVersion: 1.0.0 -maintainers: - - name: DeployStack - email: hello@deploystack.io -dependencies: - - name: db - repository: https://charts.bitnami.com/bitnami - version: ^12.0.0 - condition: dependencies.db.enabled -``` - -#### Configuring Service Connections - -```javascript -import { translate } from '@deploystack/docker-to-iac'; - -const dockerComposeContent = ` -version: "3" -services: - db: - image: mariadb:latest - environment: - - MYSQL_ROOT_PASSWORD=rootpass - app: - image: node:alpine - environment: - - DATABASE_HOST=db # This will be transformed -`; - -const result = translate(dockerComposeContent, { - source: 'compose', - target: 'DOP', // DigitalOcean App Platform - templateFormat: 'yaml', - serviceConnections: { - mappings: [ - { - fromService: 'app', // Service that needs to connect - toService: 'db', // Service to connect to - environmentVariables: [ // Env vars that reference the service - 'DATABASE_HOST' - ] - } - ] - } -}); - -// The result will include transformed service references: -console.log(result.serviceConnections); -``` - -### Example Output (AWS CloudFormation) - -```yaml -{ - files: { - 'render.yaml': { - content: 'services:\n' + - ' - name: default\n' + - ' type: web\n' + - ' env: docker\n' + - ' runtime: image\n' + - ' image:\n' + - ' url: docker.io/library/nginx:latest\n' + - ' startCommand: ""\n' + - ' plan: starter\n' + - ' region: oregon\n' + - ' envVars:\n' + - ' - key: PORT\n' + - ' value: "80"\n', - format: 'yaml', - isMain: true - } - } -} -Created: render.yaml -``` - -#### Translation with Environment Variable Generation - -```typescript -import { translate } from '@deploystack/docker-to-iac'; - -// Environment variable configuration -const envConfig = { - 'library/mariadb': { - versions: { - '*': { - environment: { - 'MYSQL_ROOT_PASSWORD': { - type: 'password', - length: 16 - }, - 'MYSQL_DATABASE': { - type: 'string', - length: 12, - pattern: 'lowercase' - } - } - } - } - } -}; - -const translatedConfig = translate(dockerComposeContent, { - source: 'compose', - target: 'CFN', - templateFormat: 'yaml', - environmentVariableGeneration: envConfig -}); -``` - -### Parameters - -#### `input: string` - -For Docker Compose: The contents of your docker-compose.yml file -For Docker run: The complete docker run command - -#### `options.source: 'run' | 'compose'` - -Specifies the input type: - -- `'run'` - For Docker run commands -- `'compose'` - For Docker Compose files - -#### `options.target: string` - -The IaC language to translate to. Currently supported targets: -Please see the sidebar on the left, section Parsers. - -#### `options.templateFormat?: TemplateFormat` - -Optional. The desired output format: - -- `'json'` - JavaScript Object Notation -- `'yaml'` - YAML format -- `'text'` - Plain text - -> [!IMPORTANT] -> Not all template formats are valid for every IaC language. For example, AWS CloudFormation only accepts YAML or JSON formats. Choose a format compatible with your target IaC language. - -#### `options.environmentVariableGeneration?: EnvironmentVariableGenerationConfig` - -Optional. Configuration for generating environment variable values. Structure: - -```typescript -type EnvironmentVariableGenerationConfig = { - [imageName: string]: { - versions: { - [version: string]: { - environment: { - [variableName: string]: { - type: 'password' | 'string' | 'number'; - length?: number; - pattern?: 'uppercase' | 'lowercase' | 'normal'; - min?: number; // For number type - max?: number; // For number type - } - } - } - } - } -} -``` - -Generation types: - -- `password`: Generates a secure random password -- `string`: Generates a random string -- `number`: Generates a random number within specified range - -Patterns (for string type): - -- `uppercase`: Only uppercase characters -- `lowercase`: Only lowercase characters -- `normal`: Mixed case with numbers - -Version matching: - -- Use exact versions (e.g., "10.5") -- Use "*" for all versions -- Use "latest" for latest version - -> [!IMPORTANT] -> Environment variables in your docker-compose.yml must use the `${VARIABLE_NAME}` syntax to be processed by the generator. - -#### `environmentVariables?: Record` - -Optional. The docker-to-iac module supports passing environment variables from `.env` files to your Infrastructure as Code templates. This feature allows you to manage configuration values separately from your Docker configurations and maintain consistency across deployments. - -```typescript -import { translate, parseEnvFile } from '@deploystack/docker-to-iac'; -import { readFileSync } from 'fs'; - -// Read and parse the .env file -const envContent = readFileSync('.env', 'utf-8'); -const envVariables = parseEnvFile(envContent); - -const result = translate(dockerConfig, { - source: 'run', // or 'compose' - target: 'RND', // or other supported targets - templateFormat: 'yaml', - environmentVariables: envVariables -}); -``` - -#### `options.persistenceKey?: string` - -Optional. The `persistenceKey` parameter allows you to maintain consistent variable values across multiple template generations. - -#### `options.serviceConnections?: ServiceConnectionsConfig` - -Optional. Configure service-to-service communications by defining which environment variables reference other services. - -```typescript -type ServiceConnectionsConfig = { - mappings: Array<{ - fromService: string; // Service that needs to connect - toService: string; // Service to connect to - environmentVariables: string[]; // Environment variables that reference the service - property?: string; // Connection property type (connectionString, hostport, etc.) - }> -}; -``` - -This option is currently supported by: - -- Render.com (RND): Uses Blueprint's `fromService` syntax -- DigitalOcean App Platform (DOP): Uses direct service names -- Kubernetes Helm Charts (HELM): Uses Kubernetes DNS service discovery - -Example: - -```javascript -serviceConnections: { - mappings: [ - { - fromService: 'frontend', - toService: 'api', - environmentVariables: ['API_URL'], - property: 'hostport' - }, - { - fromService: 'app', - toService: 'db', - environmentVariables: ['DATABASE_URL'], - property: 'connectionString' - } - ] -} -``` - -### Return Value - -Returns the translated Infrastructure as Code template and any resolved service connections: - -```typescript -{ - files: { - // Generated IaC template files with paths as keys - 'render.yaml': { content: '...', format: 'yaml', isMain: true } - }, - serviceConnections: [ - { - fromService: 'app', - toService: 'db', - variables: { - 'DATABASE_HOST': { - originalValue: 'db', - transformedValue: 'db' // Transformed as appropriate for the provider - } - } - } - ] -} -``` - -## List Services API - -Extract service configurations from either Docker run commands or docker-compose.yml files as structured JSON objects. - -### Function Signature - -```typescript -listServices(content: string, options: ListServicesOptions): { [key: string]: ServiceConfig } - -type ListServicesOptions = { - source: 'compose' | 'run'; - environmentVariableGeneration?: EnvironmentVariableGenerationConfig; - environmentVariables?: Record; - persistenceKey?: string; -}; -``` - -### Examples - -#### Listing Docker Compose Services with Environment Variables - -```javascript -import { readFileSync } from 'fs'; -import { listServices, parseEnvFile } from '@deploystack/docker-to-iac'; - -const dockerComposeContent = readFileSync('path/to/docker-compose.yml', 'utf8'); -const envContent = readFileSync('.env', 'utf-8'); -const envVariables = parseEnvFile(envContent); - -const services = listServices(dockerComposeContent, { - source: 'compose', - environmentVariables: envVariables -}); - -console.log(services); -``` - -##### Output with Environment Variables - -```json -{ - "db": { - "image": "mariadb:11.2", - "ports": [], - "command": "mariadbd --character-set-server=utf8mb4 --collation-server=utf8mb4_bin", - "restart": "unless-stopped", - "volumes": [{"host": "db", "container": "/var/lib/mysql"}], - "environment": { - "MYSQL_ROOT_PASSWORD": "mysecretpassword", - "MYSQL_USER": "myuser", - "MYSQL_PASSWORD": "mysecretpassword", - "MYSQL_DATABASE": "mydatabase" - } - } -} -``` - -#### Listing Docker Run Services - -```javascript -import { listServices } from '@deploystack/docker-to-iac'; - -const dockerRunCommand = 'docker run -d -p 8080:80 -e NODE_ENV=production nginx:latest'; - -const services = listServices(dockerRunCommand, { - source: 'run' -}); - -console.log(services); -``` - -##### Output - -```json -{ - "service": { - "image": "nginx:latest", - "ports": ["8080:80"], - "environment": { - "NODE_ENV": "production" - } - } -} -``` - -### Options - -#### `content: string` - -The input content to parse: - -- For Docker Compose: The contents of your docker-compose.yml file -- For Docker run: The complete docker run command - -#### `options.source: 'run' | 'compose'` - -Specifies the input type: - -- `'run'` - For Docker run commands -- `'compose'` - For Docker Compose files - -#### `options.environmentVariables?: Record` - -Optional. Environment variables from a `.env` file or other source. Used to substitute variables in the format `${VARIABLE_NAME}` in your Docker configuration. - -Example: - -```javascript -const envVariables = { - 'DB_PASSWORD': 'mysecretpassword', - 'DB_USERNAME': 'myuser', - 'DB_DATABASE': 'mydatabase' -}; -``` - -#### `options.environmentVariableGeneration?: EnvironmentVariableGenerationConfig` - -Optional. Configuration for automatically generating environment variable values. Structure: - -```typescript -type EnvironmentVariableGenerationConfig = { - [imageName: string]: { - versions: { - [version: string]: { - environment: { - [variableName: string]: { - type: 'password' | 'string' | 'number'; - length?: number; - pattern?: 'uppercase' | 'lowercase' | 'normal'; - min?: number; // For number type - max?: number; // For number type - } - } - } - } - } -} -``` - -Example: - -```javascript -const envGeneration = { - 'library/mariadb': { - versions: { - '*': { - environment: { - 'MYSQL_ROOT_PASSWORD': { - type: 'password', - length: 16 - }, - 'MYSQL_DATABASE': { - type: 'string', - length: 12, - pattern: 'lowercase' - } - } - } - } - } -}; -``` - -#### `options.persistenceKey?: string` - -Optional. A unique key to maintain consistent generated environment variables across multiple calls to `listServices` or `translate`. - -### Return Value - -Returns an object where: - -- Keys are service names -- Values are service configurations containing: - - `image`: Docker image name and tag - - `ports`: Array of port mappings - - `command`: Custom command (if specified) - - `restart`: Restart policy (if specified) - - `volumes`: Array of volume mappings (if specified) - - `environment`: Object of environment variables - -## Parse Environment File - -Parse a `.env` file content into a key-value object using the `parseEnvFile()` method. The method handles basic environment file syntax including comments and quoted values. - -### Example - -```typescript -import { parseEnvFile } from '@deploystack/docker-to-iac'; - -const envContent = ` -# Database settings -DB_HOST=localhost -DB_USER="admin" -DB_PASS='secretpass' -# Comment line -NUMBERS=123456 -QUOTED="value=with=equals" -`; - -const envVars = parseEnvFile(envContent); - -console.log('Parsed Environment Variables:'); -console.log(envVars); -``` - -#### Output - -```json -{ - "DB_HOST": "localhost", - "DB_USER": "admin", - "DB_PASS": "secretpass", - "NUMBERS": "123456", - "QUOTED": "value=with=equals" -} -``` - -### Type - -```typescript -parseEnvFile(content: string): Record -``` diff --git a/tmp/docker-to-iac/available-commands.mdx b/tmp/docker-to-iac/available-commands.mdx deleted file mode 100644 index 22c3ec3..0000000 --- a/tmp/docker-to-iac/available-commands.mdx +++ /dev/null @@ -1,78 +0,0 @@ ---- -title: Available Commands -description: List of all available commands that you can use to help us with development and testing -menuTitle: Available Commands ---- - -# docker-to-iac Available Commands - -The following commands are currently supported: - -## Build Commands - -- `npm run build` - - Builds the module using TypeScript compiler and creates output files inside the `dist/` directory. - -## Code Quality Commands - -- `npm run lint` - - Runs ESLint to check code quality. ESLint is also run as part of GitHub action test for new pull requests on the default `main` branch. - -## Testing Commands - -- `npm run test` - - Runs the complete test suite including both unit tests and end-to-end tests. -- `npm run test:unit` - - Runs only the unit tests to validate individual components. -- `npm run test:e2e` - - Runs only the end-to-end tests which validate the entire translation process from Docker run commands or Docker Compose files to infrastructure as code. -- `npm run test:watch` - - Runs tests in watch mode, which automatically re-runs tests when files change. -- `npm run test:coverage` - - Runs tests with coverage reporting to identify untested code paths. - -## Release Commands - -- `npm run release` - - Runs the release-it command which is part of the release process of [docker-to-iac](https://www.npmjs.com/package/@deploystack/docker-to-iac) modules to npm registry. The release is executed through configurations defined in `.release-it.js`. - -## Other Commands - -- `npm run pretest:e2e` - - Automatically run before e2e tests to clean the output directory. - -You can view all commands and their configurations in the [package.json](https://github.com/deploystackio/docker-to-iac/blob/main/package.json) file. - -## Examples - -### Running Unit Tests Only - -```bash -npm run test:unit -``` - -### Running End-to-End Tests Only - -```bash -npm run test:e2e -``` - -### Running All Tests with Coverage - -```bash -npm run test:coverage -``` - -### Building the Module - -```bash -npm run build -``` - -### Checking Code Quality - -```bash -npm run lint -``` - -Each command is configured to provide the most relevant feedback for its purpose. For example, unit tests provide detailed output about each individual function, while end-to-end tests show a summary of the complete translation process from Docker configurations to infrastructure as code. diff --git a/tmp/docker-to-iac/before-you-start.mdx b/tmp/docker-to-iac/before-you-start.mdx deleted file mode 100644 index 8685447..0000000 --- a/tmp/docker-to-iac/before-you-start.mdx +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Before you Start contributing -description: Contribute to DeployStack by adding cloud providers that support Docker runtime and infrastructure as code. Your work benefits the entire open-source community. -menuTitle: Before you Start contributing ---- - -# Before you start contributing to docker-to-iac module - -Thank you for your interest in extending the module. Please remember that [docker-to-iac](https://github.com/deploystackio/docker-to-iac) open-source module is the heart of the DeployStack platform. - -## Adding a new cloud provider - -This means: if your pull request will get approved, all existing applications in our catalog [https://deploystack.io/c/](https://deploystack.io/c) will be expanded to include another cloud provider that you want to add. - -That sounds great, you are helping all open source applications inside our catalog. - -There is one thing to keep in mind: - -### Docker Container Runtime - -The platform you want to add to the docker-to-iac module must have a docker runtime like Render.com or DigitalOcean. - -Currently, our catalog only includes dockerized applications. Therefore, they also need a runtime environment where the Docker container can be executed. - -### Infrastructure as Code - -Our platform's advantage is that visitors to an open source repository can deploy an application using the one-click deploy button. - -Therefore, the new cloud provider must supply the option and allow infrastructure as code teamplte. The template can be something custom like CloudFormation from AWS or something generic like Terraform (although Terraform is not generic, that's a bad example 😄). - -However, one-click deployment or a similar mechanism/automation __must__ be available. diff --git a/tmp/docker-to-iac/environment-variable-generation.mdx b/tmp/docker-to-iac/environment-variable-generation.mdx deleted file mode 100644 index 78b1fff..0000000 --- a/tmp/docker-to-iac/environment-variable-generation.mdx +++ /dev/null @@ -1,209 +0,0 @@ ---- -title: Environment Variable Generation -description: Use docker-to-iac to automatically create environment variables for your Docker containers. Define rules for variable generation and maintain consistency across multiple deployments. -menuTitle: Environment Variable Generation ---- - -# Environment Variable Generation - -The docker-to-iac module includes a system for handling environment variables, with a focus on database images and services that require secure credentials. This feature automatically generates appropriate values for environment variables and can maintain consistency across multiple template generations. - -## Overview - -When working with databases and other services that require credentials, you often need to generate secure passwords and consistent configuration values. The environment variable generation system: - -- Automatically generates credentials and configuration values -- Maintains consistency across multiple template generations -- Handles version-specific variable names -- Supports different variable types (passwords, strings, numbers) - -## Configuration Structure - -Environment variable configurations are defined using a JSON structure that maps Docker images to their version-specific environment requirements: - -```typescript -type EnvironmentVariableConfig = { - [imageName: string]: { - versions: { - [version: string]: { - environment: { - [variableName: string]: { - type: 'password' | 'string' | 'number'; - length?: number; - pattern?: 'uppercase' | 'lowercase' | 'normal'; - min?: number; // For number type - max?: number; // For number type - } - } - } - } - } -} -``` - -## Usage Example - -Here's how to use environment variable generation with a MariaDB container: - -```javascript -import { translate } from '@deploystack/docker-to-iac'; - -// Define environment variable generation configuration -const envConfig = { - 'library/mariadb': { - versions: { - '>=11.0': { - environment: { - 'MYSQL_ROOT_PASSWORD': { - type: 'password', - length: 16 - }, - 'MYSQL_USER': { - type: 'string', - length: 8, - pattern: 'lowercase' - }, - 'MYSQL_PASSWORD': { - type: 'password', - length: 16 - }, - 'MYSQL_DATABASE': { - type: 'string', - length: 12, - pattern: 'lowercase' - } - } - } - } - } -}; - -// Your docker-compose.yml content with variable placeholders -const dockerComposeContent = ` -version: '3' -services: - db: - image: mariadb:latest - environment: - MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD} - MYSQL_USER: ${MYSQL_USER} - MYSQL_PASSWORD: ${MYSQL_PASSWORD} - MYSQL_DATABASE: ${MYSQL_DATABASE} -`; - -// Generate templates with persistent variables -const result1 = translate(dockerComposeContent, { - source: 'compose', - target: 'CFN', - templateFormat: 'yaml', - environmentVariableGeneration: envConfig, - persistenceKey: 'my-unique-key' // Use this to maintain consistent values -}); - -// Generate for another provider, reusing the same variables -const result2 = translate(dockerComposeContent, { - source: 'compose', - target: 'RND', - templateFormat: 'yaml', - environmentVariableGeneration: envConfig, - persistenceKey: 'my-unique-key' // Same key ensures same values are used -}); -``` - -## Variable Types - -### Password Type - -Generates secure random passwords: - -```json -{ - "type": "password", - "length": 16 // Optional, defaults to 16 -} -``` - -### String Type - -Generates random strings with specified patterns: - -```json -{ - "type": "string", - "length": 8, // Optional, defaults to 8 - "pattern": "lowercase" // Optional: "uppercase", "lowercase", or "normal" -} -``` - -### Number Type - -Generates random numbers within a specified range: - -```json -{ - "type": "number", - "min": 1000, // Optional, defaults to 1 - "max": 9999 // Optional, defaults to 1000000 -} -``` - -## Version Matching - -The system supports semantic version matching: - -- Version ranges: `">=11.0"`, `"<=10.5"` -- Exact versions: `"10.5"`, `"11.2"` -- Wildcard: `"*"` (matches any version) -- Latest: `"latest"` (matches latest version) - -Example with version-specific configurations: - -```json -{ - "library/mariadb": { - "versions": { - ">=11.0": { - "environment": { - "MYSQL_ROOT_PASSWORD": { - "type": "password", - "length": 16 - } - } - }, - "<=10.5": { - "environment": { - "MARIADB_ROOT_PASSWORD": { - "type": "password", - "length": 20 - } - } - } - } - } -} -``` - -## Persistence Key - -The `persistenceKey` parameter allows you to maintain consistent variable values across multiple template generations: - -- Use the same key when generating templates for different providers -- Generated values are cached and reused when the same key is provided -- Different keys will generate new sets of values -- Keys should be unique to your specific use case - -## Important Notes - -- Only variables using the `${VARIABLE_NAME}` syntax will be processed -- Variables without corresponding config entries retain their original values -- Generated passwords meet common security requirements (mixed case, numbers, special characters) -- String patterns affect the character set used in generation -- Version matching uses semantic versioning for comparison -- The `persistenceKey` should be unique to your specific deployment scenario - -## Limitations - -- Only supports public Docker Hub images currently -- Cannot generate values for build-time variables -- No support for complex variable dependencies -- Version matching requires valid semantic versions diff --git a/tmp/docker-to-iac/environment-variable.mdx b/tmp/docker-to-iac/environment-variable.mdx deleted file mode 100644 index bb0ad33..0000000 --- a/tmp/docker-to-iac/environment-variable.mdx +++ /dev/null @@ -1,199 +0,0 @@ ---- -title: Environment Variables in docker-to-iac -description: Learn how to manage environment variables in docker-to-iac. Pass configuration values from .env files to your Infrastructure as Code templates and keep your sensitive data secure. -menuTitle: Environment Variables ---- - -# Environment Variables - -The docker-to-iac module supports passing environment variables from `.env` files to your Infrastructure as Code templates. This feature allows you to manage configuration values separately from your Docker configurations and maintain consistency across deployments. - -## Overview - -When translating Docker configurations to Infrastructure as Code templates, you can provide environment variables that will be used to replace placeholders in your Docker configurations. This is particularly useful for: - -- Managing configuration values separately from Docker files -- Providing credentials and sensitive information -- Maintaining consistent values across different deployment environments - -## Usage - -### Reading Environment Variables - -The module provides a utility function `parseEnvFile` to read and parse `.env` files: - -```javascript -import { translate, parseEnvFile } from '@deploystack/docker-to-iac'; -import { readFileSync } from 'fs'; - -// Read and parse the .env file -const envContent = readFileSync('.env', 'utf-8'); -const envVariables = parseEnvFile(envContent); -``` - -### Using Environment Variables in Translation - -Pass the environment variables to the `translate` function using the `environmentVariables` option: - -```javascript -const result = translate(dockerConfig, { - source: 'run', // or 'compose' - target: 'RND', // or other supported targets - templateFormat: 'yaml', - environmentVariables: envVariables -}); -``` - -## Default Values - -The docker-to-iac module supports Docker's default value syntax for environment variables. This allows you to specify fallback values that are used when environment variables are not provided or are undefined. - -### Syntax - -Default values can be specified using the `${VARIABLE:-default}` syntax, where: - -- `VARIABLE` is the environment variable name -- `default` is the value used if `VARIABLE` is not set - -### Docker Compose Example - -```yaml -services: - db: - image: postgres:15-alpine - environment: - POSTGRES_USER: ${DB_USER:-defaultuser} - POSTGRES_PASSWORD: ${DB_PASSWORD:-secret123} - POSTGRES_DB: ${DB_NAME:-myapp} -``` - -### Docker Run Example - -```bash -docker run -d \ - --name db \ - -e POSTGRES_USER=${DB_USER:-defaultuser} \ - -e POSTGRES_PASSWORD=${DB_PASSWORD:-secret123} \ - -e POSTGRES_DB=${DB_NAME:-myapp} \ - postgres:15-alpine -``` - -### How Default Values Work - -The module processes default values in this order: - -1. If an environment variable is provided via `.env` file or `environmentVariables` option, that value is used -2. If no environment variable is found, the default value after `:-` is used -3. If neither exists, an empty string is used - -For example: - -```javascript -// With this .env file: -DB_USER=johndoe -// DB_PASSWORD is not set - -// And this docker-compose.yml: -environment: - POSTGRES_USER: ${DB_USER:-defaultuser} - POSTGRES_PASSWORD: ${DB_PASSWORD:-secret123} - -// The resolved values will be: -POSTGRES_USER: "johndoe" // From .env file -POSTGRES_PASSWORD: "secret123" // Default value used -``` - -Default values provide a way to: - -- Make your configurations more robust by handling missing variables -- Set sensible defaults for development environments -- Ensure required values always have a fallback - -## Complete Example - -Here's a complete example showing how to use environment variables with a MariaDB container: - -```javascript -import { translate, parseEnvFile } from '@deploystack/docker-to-iac'; -import { readFileSync } from 'fs'; - -// Read the .env file -const envContent = readFileSync('.env', 'utf-8'); -const envVariables = parseEnvFile(envContent); - -// Docker run command with environment variable placeholders -const dockerRunCommand = `docker run -d \ - --name mariadb \ - -e MYSQL_ROOT_PASSWORD=\${DB_PASSWORD} \ - -e MYSQL_USER=\${DB_USERNAME} \ - -e MYSQL_PASSWORD=\${DB_PASSWORD} \ - -e MYSQL_DATABASE=\${DB_DATABASE} \ - -v db:/var/lib/mysql \ - docker.io/library/mariadb:11.2`; - -// Translate with environment variables -const result = translate(dockerRunCommand, { - source: 'run', - target: 'RND', - templateFormat: 'yaml', - environmentVariables: envVariables -}); -``` - -### .env File Format - -Your `.env` file should follow standard environment file format: - -```bash -# .env -DB_USERNAME=myuser -DB_PASSWORD=mysecretpassword -DB_DATABASE=mydatabase -``` - -### Variable Substitution - -Environment variables are substituted using the `${VARIABLE_NAME}` syntax in your Docker configurations: - -```yaml -# In docker-compose.yml -services: - db: - image: mariadb:11.2 - environment: - MYSQL_ROOT_PASSWORD: ${DB_PASSWORD} - MYSQL_USER: ${DB_USERNAME} - MYSQL_PASSWORD: ${DB_PASSWORD} - MYSQL_DATABASE: ${DB_DATABASE} -``` - -## Working with Docker Compose - -The environment variables feature works with both Docker run commands and docker-compose.yml files: - -```javascript -// For docker-compose.yml -const dockerComposeContent = readFileSync('docker-compose.yml', 'utf-8'); - -const result = translate(dockerComposeContent, { - source: 'compose', - target: 'RND', - templateFormat: 'yaml', - environmentVariables: envVariables -}); -``` - -## Important Notes - -- Environment variables take precedence over default values in Docker configurations -- Missing environment variables will result in empty values in the output templates -- The module does not validate environment variable values -- Sensitive information should be handled securely -- Variable names are case-sensitive - -## Limitations - -- Only supports basic environment variable substitution -- No support for variable expansion or shell-style variable manipulation -- Cannot reference other environment variables within values -- No built-in encryption for sensitive values diff --git a/tmp/docker-to-iac/example-of-a-new-parser.mdx b/tmp/docker-to-iac/example-of-a-new-parser.mdx deleted file mode 100644 index a7b949f..0000000 --- a/tmp/docker-to-iac/example-of-a-new-parser.mdx +++ /dev/null @@ -1,384 +0,0 @@ ---- -title: Example of a New Parser -description: Example code for adding a new parser to docker-to-iac, supporting both Docker run commands and Docker Compose files, with multi-file output and service connections -menuTitle: Adding a New Parser ---- - -# Adding a New Parser - -> [!TIP] -> Thank you for your interest in collaborating! The docker-to-iac module will remain open source forever, helping simplify deployments across cloud providers without vendor lock-in. - -## Parser Implementation - -Create a new file inside `src/parsers/new-provider.ts`: - -```typescript -import { - BaseParser, - ParserInfo, - TemplateFormat, - ParserConfig, - FileOutput, - DockerImageInfo -} from './base-parser'; -import { ApplicationConfig } from '../types/container-config'; -import { parsePort } from '../utils/parsePort'; -import { parseCommand } from '../utils/parseCommand'; - -// Define default configuration for your parser -const defaultParserConfig: ParserConfig = { - files: [ - { - path: 'awesome-iac.yaml', - templateFormat: TemplateFormat.yaml, - isMain: true, - description: 'Main IaC configuration file' - }, - { - path: 'templates/resources.yaml', - templateFormat: TemplateFormat.yaml, - description: 'Additional resources configuration' - } - ], - cpu: 512, - memory: '1GB', - region: 'default-region', - subscriptionName: 'basic-tier' -}; - -// Optional: Add helper functions for your specific provider -function getNewProviderServiceType(imageInfo: DockerImageInfo): string { - // Logic to determine service type based on image - // Example: Check if it's a database, web service, etc. - return 'web-service'; // Default type -} - -// Optional: Add function to determine if an image is a managed service -function isNewProviderManagedService(imageInfo: DockerImageInfo): boolean { - // Check if this image should be handled as a managed service - const imageUrl = `${imageInfo.repository}:${imageInfo.tag || 'latest'}`; - return imageUrl.includes('postgres') || imageUrl.includes('redis'); -} - -class NewProviderParser extends BaseParser { - // Multi-file implementation - required by BaseParser - parseFiles(config: ApplicationConfig): { [path: string]: FileOutput } { - // Initialize result containers - const services: Array = []; - const managedServices: Array = []; - - // Track service mappings for managed services - const managedServiceMap = new Map(); - - // First pass: identify and register managed services - for (const [serviceName, serviceConfig] of Object.entries(config.services)) { - if (isNewProviderManagedService(serviceConfig.image)) { - // Create a managed service instead of a regular service - const managedName = `${serviceName}-managed`; - - // Track the mapping for service connections later - managedServiceMap.set(serviceName, managedName); - - // Add to managed services collection - managedServices.push({ - name: managedName, - type: getNewProviderServiceType(serviceConfig.image), - // Add provider-specific managed service properties - plan: defaultParserConfig.subscriptionName - }); - - // Skip further processing of this service - continue; - } - - // Regular services will be processed in the second pass - } - - // Second pass: process regular services with their connections - for (const [serviceName, serviceConfig] of Object.entries(config.services)) { - // Skip managed services already processed - if (managedServiceMap.has(serviceName)) { - continue; - } - - // Extract ports from service configuration - const ports = new Set(); - if (serviceConfig.ports) { - serviceConfig.ports.forEach(port => { - if (typeof port === 'object' && port !== null) { - ports.add(port.container); - } else { - const parsedPort = parsePort(port); - if (parsedPort) { - ports.add(parsedPort); - } - } - }); - } - - // Prepare basic service definition - const service: any = { - name: serviceName, - type: getNewProviderServiceType(serviceConfig.image), - image: serviceConfig.image, - command: parseCommand(serviceConfig.command), - environment: [] - }; - - // Add ports if available - if (ports.size > 0) { - service.ports = Array.from(ports); - } - - // Process service connections if available - if (config.serviceConnections) { - // First add regular environment variables - for (const [key, value] of Object.entries(serviceConfig.environment)) { - // Check if this variable is handled by service connections - const isHandledByConnection = config.serviceConnections.some(conn => - conn.fromService === serviceName && - Object.keys(conn.variables).includes(key) - ); - - if (!isHandledByConnection) { - // Regular environment variable - service.environment.push({ - key, - value: value.toString() - }); - } - } - - // Then add service connection variables with provider-specific syntax - for (const connection of config.serviceConnections) { - if (connection.fromService === serviceName) { - for (const [varName, varInfo] of Object.entries(connection.variables)) { - // Check if target is a managed service - if (managedServiceMap.has(connection.toService)) { - const targetName = managedServiceMap.get(connection.toService); - - // Use provider-specific reference syntax - service.environment.push({ - key: varName, - // Example: ${resources.MANAGED_SERVICE_NAME.CONNECTION_STRING} - value: `\${resources.${targetName}.${connection.property || 'connectionString'}}` - }); - } else { - // Regular service connection - service.environment.push({ - key: varName, - // Example: ${services.SERVICE_NAME.HOST_PORT} - value: `\${services.${connection.toService}.${connection.property || 'hostport'}}` - }); - } - } - } - } - } else { - // No service connections, just add all environment variables - service.environment = Object.entries(serviceConfig.environment).map(([key, value]) => ({ - key, - value: value.toString() - })); - } - - // Add service to collection - services.push(service); - } - - // Create main configuration - const mainConfig = { - version: '1.0', - provider: 'new-provider', - region: defaultParserConfig.region, - services - }; - - // Create resources configuration if we have managed services - const resourcesConfig = managedServices.length > 0 ? { - version: '1.0', - managedResources: managedServices - } : {}; - - // Return file mappings - the main file is required - const result: { [path: string]: FileOutput } = { - 'awesome-iac.yaml': { - content: this.formatFileContent(mainConfig, TemplateFormat.yaml), - format: TemplateFormat.yaml, - isMain: true - } - }; - - // Add resources file if we have managed services - if (managedServices.length > 0) { - result['templates/resources.yaml'] = { - content: this.formatFileContent(resourcesConfig, TemplateFormat.yaml), - format: TemplateFormat.yaml - }; - } - - return result; - } - - getInfo(): ParserInfo { - return { - providerWebsite: "https://newprovider.example.com", - providerName: "New Provider Cloud", - providerNameAbbreviation: "NP", - languageOfficialDocs: "https://docs.newprovider.example.com/iac", - languageAbbreviation: "NP", - languageName: "New Provider IaC", - defaultParserConfig - }; - } -} - -export default new NewProviderParser(); -``` - -## Configuration and Provider-Specific Logic - -### Service Type Detection - -Create a file for service type configuration in `src/config/newprovider/service-types.ts`: - -```typescript -interface NewProviderServiceTypeConfig { - type: string; - description: string; - versions: string; - isManaged?: boolean; -} - -interface NewProviderServiceTypesConfig { - serviceTypes: { - [key: string]: NewProviderServiceTypeConfig; - }; -} - -export const newProviderServiceTypesConfig: NewProviderServiceTypesConfig = { - serviceTypes: { - 'docker.io/library/mariadb': { - type: 'database', - description: 'MariaDB database service', - versions: '*' - }, - 'docker.io/library/postgres': { - type: 'database', - description: 'PostgreSQL database', - versions: '*', - isManaged: true - }, - 'docker.io/library/redis': { - type: 'cache', - description: 'Redis cache', - versions: '*', - isManaged: true - } - } -}; - -export function getNewProviderServiceType(imageString: string): string { - const baseImage = imageString.split(':')[0]; - return newProviderServiceTypesConfig.serviceTypes[baseImage]?.type || 'web'; -} - -export function isNewProviderManagedService(imageString: string): boolean { - const baseImage = imageString.split(':')[0]; - return !!newProviderServiceTypesConfig.serviceTypes[baseImage]?.isManaged; -} - -export type { NewProviderServiceTypeConfig, NewProviderServiceTypesConfig }; -``` - -### Service Connection Properties - -Update the service connection properties in `src/config/connection-properties.ts`: - -```typescript -export const servicePropertyMappings: Record = { - 'host': { - render: 'host', - digitalOcean: 'PRIVATE_DOMAIN', - newProvider: 'HOST' // Add your provider mapping - }, - 'port': { - render: 'port', - digitalOcean: 'PRIVATE_PORT', - newProvider: 'PORT' // Add your provider mapping - }, - 'hostport': { - render: 'hostport', - digitalOcean: 'PRIVATE_URL', - newProvider: 'ENDPOINT' // Add your provider mapping - } -}; - -export const databasePropertyMappings: Record = { - 'connectionString': { - render: 'connectionString', - digitalOcean: 'DATABASE_URL', - newProvider: 'CONNECTION_STRING' // Add your provider mapping - }, - // Add other mappings... -}; -``` - -## Adding Your Parser to the System - -Update `src/index.ts` to include your new parser: - -```typescript -// Import your new parser -import newProviderParserInstance from './parsers/new-provider'; - -// Add it to the parsers array -const parsers: BaseParser[] = [ - cloudFormationParserInstance, - renderParserInstance, - digitalOceanParserInstance, - newProviderParserInstance // Add your parser here -]; -``` - -## Testing - -Please read our guidelines for testing parsers in the [Testing section](/docs/docker-to-iac/testing.md). - -## New parser documentation - -Please update documentation in the [github.com/deploystackio/documentation](https://github.com/deploystackio/documentation) repository. - -## Checklist - -1. Support both input types: - - Docker run commands - - Docker Compose files - -2. Handle all service types: - - Regular web/application services - - Managed database services - - Cache services - -3. Handle resource mappings consistently: - - Container ports - - Environment variables - - Volume mounts - - Resource limits - - Service connections - -4. Process service connections correctly: - - Service-to-service references - - Service-to-managed-service references - - Use provider-specific connection syntax - -5. Provide clear error messages for: - - Unsupported features - - Invalid configurations - - Missing required fields - -6. Test edge cases: - - Multiple services with interdependencies - - Complex configurations with service connections - - Various image formats and service types diff --git a/tmp/docker-to-iac/limitations.mdx b/tmp/docker-to-iac/limitations.mdx deleted file mode 100644 index 55dfa0a..0000000 --- a/tmp/docker-to-iac/limitations.mdx +++ /dev/null @@ -1,90 +0,0 @@ ---- -title: Limitations for docker-to-iac module -description: Current limitations and constraints of the docker-to-iac module -menuTitle: Limitations ---- - -# Limitations for docker-to-iac module - -## Registry Support - -The module currently supports Docker images from -> please check [Supported Registries for docker-to-iac module](/docs/docker-to-iac/supported-registries.md) - -## Docker Image Requirement - -The `docker-to-iac` module is designed to work exclusively with pre-built Docker images. This means that each service in your `docker-compose.yml` file must specify an `image` property. - -## Volume Support - -When working with volume mappings in your Docker configuration, be aware that volume support varies among cloud providers: - -- Some providers fully support multiple volume mappings -- Some providers only support the first volume mapping defined in your configuration -- Some providers support ephemeral files only, meaning no persistent volume storage is available -- Volume mapping implementation details can differ between providers - -Please check the specific provider's documentation to understand their volume mapping capabilities and limitations before deployment. - -For example, if your Docker configuration includes multiple volumes: - -```yaml -services: - app: - image: nginx:latest - volumes: - - ./config:/etc/nginx/conf.d - - ./logs:/var/log/nginx - - ./data:/usr/share/nginx/html -``` - -Depending on your chosen provider: - -- All volume mappings might be supported -- Only the first volume mapping (`./config:/etc/nginx/conf.d`) might be implemented -- No volumes might be supported, with only ephemeral storage available - -We recommend reviewing your target provider's documentation for detailed information about their volume support capabilities. - -### Build Instructions Not Supported - -The module does not support services that use the `build` directive. For example: - -```yaml [docker-compose.yml] -# ❌ Not Supported -services: - app: - build: - context: ./build/app - dockerfile: Dockerfile -``` - -Instead, you must use pre-built images: - -```yaml [docker-compose.yml] -# ✅ Supported -services: - app: - image: nginx:latest -``` - -#### Rationale - -This limitation exists because Infrastructure as Code (IaC) templates require specific, immutable container images to ensure consistent deployments. The infrastructure and the selection of cloud providers for this docker-to-iac module only allow pre-build container images. It is technically not possible to create a build with the preconfigured infrastructure. This is why the pre-build check was built in. This happens also because the scope of this module is only pre-build container. - -### Workaround - -If you need to use custom Docker images: - -Build your Docker images locally or in your CI/CD pipeline -Push them to a container registry (like Docker Hub, GitHub Container Registry, or AWS ECR) -Reference the pushed image in your docker-compose file using the image property - -For example: - -```yaml -services: - app: - image: ghcr.io/your-org/your-app:1.0.0 -``` - -This ensures that your IaC templates will have access to the exact same container image across all deployments. diff --git a/tmp/docker-to-iac/meta.json b/tmp/docker-to-iac/meta.json deleted file mode 100644 index 510946c..0000000 --- a/tmp/docker-to-iac/meta.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "title": "Docker-to-IAC", - "description": "Documentation for Docker-to-IAC", - "root": true -} diff --git a/tmp/docker-to-iac/multi-file-configuration.mdx b/tmp/docker-to-iac/multi-file-configuration.mdx deleted file mode 100644 index 74cba0c..0000000 --- a/tmp/docker-to-iac/multi-file-configuration.mdx +++ /dev/null @@ -1,192 +0,0 @@ ---- -title: Multi-File Configuration in docker-to-iac -description: Learn how docker-to-iac supports complex Infrastructure as Code templates with multiple interconnected files, including Helm Charts and other multi-file IaC formats. -menuTitle: Multi-File Configuration ---- - -# Multi-File Configuration in docker-to-iac - -## Introduction to Multi-File Support - -Starting with version 1.20.0, [docker-to-iac](https://github.com/deploystackio/docker-to-iac) supports generating multiple interconnected files for more complex Infrastructure as Code (IaC) templates. This feature was introduced primarily to support Helm Charts and other sophisticated IaC formats that require multiple files with specific directory structures. - -## Why Multi-File Templates? - -Modern IaC solutions often require multiple files that work together: - -- **Helm Charts** need Chart.yaml, values.yaml, and template files -- **Terraform modules** use main.tf, variables.tf, outputs.tf, and more -- **Kubernetes manifests** are typically split into multiple YAML files -- **Multi-tier applications** may need separate configurations for each tier - -These complex deployments would be difficult or impossible to represent in a single file, which led to the introduction of multi-file support. - -## The Main File Concept - -Each parser must designate one file as the "main" file using the `isMain: true` property. This maintains backward compatibility with existing code and provides a clear entry point for deployment tools. - -```typescript -parseFiles(config: ApplicationConfig): { [path: string]: FileOutput } { - return { - 'Chart.yaml': { - content: this.formatFileContent(chartConfig, TemplateFormat.yaml), - format: TemplateFormat.yaml, - isMain: true // This is the main file - }, - 'values.yaml': { - content: this.formatFileContent(valuesConfig, TemplateFormat.yaml), - format: TemplateFormat.yaml - } - }; -} -``` - -When a parser is invoked through the legacy `parse()` method, only the content of the main file is returned. However, when using the `parseFiles()` method, all files are included in the response. - -## Example: Helm Chart Structure - -Helm Charts are a perfect example of why multi-file support is needed. A basic Helm Chart requires at least the following files: - -```bash -mychart/ -├── Chart.yaml # Chart metadata -├── values.yaml # Default configuration values -└── templates/ - ├── deployment.yaml # Kubernetes Deployment - ├── service.yaml # Kubernetes Service - └── _helpers.tpl # Template helpers -``` - -The docker-to-iac module now includes a Helm parser that generates this exact structure when translating Docker configurations to Helm Charts: - -```javascript -const result = translate(dockerComposeContent, { - source: 'compose', - target: 'HELM', - templateFormat: 'yaml' -}); - -// Result contains all files needed for a complete Helm Chart -console.log(Object.keys(result.files)); -// [ -// 'Chart.yaml', -// 'values.yaml', -// 'templates/deployment.yaml', -// 'templates/service.yaml', -// 'templates/configmap.yaml', -// 'templates/secret.yaml', -// 'templates/NOTES.txt', -// 'templates/_helpers.tpl' -// ] -``` - -With the multi-file support, a Helm Chart parser configuration might look like: - -```typescript -const defaultParserConfig: ParserConfig = { - files: [ - { - path: 'Chart.yaml', - templateFormat: TemplateFormat.yaml, - isMain: true, - description: 'Chart metadata file' - }, - { - path: 'values.yaml', - templateFormat: TemplateFormat.yaml, - description: 'Default configuration values' - }, - { - path: 'templates/deployment.yaml', - templateFormat: TemplateFormat.yaml, - description: 'Kubernetes Deployment template' - }, - { - path: 'templates/service.yaml', - templateFormat: TemplateFormat.yaml, - description: 'Kubernetes Service template' - }, - { - path: 'templates/_helpers.tpl', - templateFormat: TemplateFormat.text, - description: 'Template helper functions' - } - ] -}; -``` - -## Implementation Details - -### File Structure - -Each parser must implement the `parseFiles` method, which returns an object mapping file paths to their content: - -```typescript -interface FileOutput { - content: string; // File content as a string - format: TemplateFormat; // Format (yaml, json, text) - isMain?: boolean; // Whether this is the main file -} - -parseFiles(config: ApplicationConfig): { [path: string]: FileOutput }; -``` - -### Directory Support - -The file paths can include directories, which will be created automatically when the templates are saved: - -```typescript -return { - 'templates/deployment.yaml': { - content: deploymentContent, - format: TemplateFormat.yaml - }, - 'templates/ingress.yaml': { - content: ingressContent, - format: TemplateFormat.yaml - } -}; -``` - -### Content Formatting - -The `formatFileContent` helper method ensures that content is properly formatted according to the specified template format. - -## Backward Compatibility - -To maintain backward compatibility, the `BaseParser` class implements a default `parse` method that: - -1. Calls the new `parseFiles` method -2. Finds the file marked with `isMain: true` -3. Returns only that file's content - -```typescript -parse(config: ApplicationConfig, templateFormat?: TemplateFormat): any { - const files = this.parseFiles(config); - const mainFile = Object.values(files).find(file => file.isMain); - - if (!mainFile) { - throw new Error('No main file defined in parser output'); - } - - return typeof mainFile.content === 'string' - ? mainFile.content - : formatResponse(JSON.stringify(mainFile.content, null, 2), templateFormat || mainFile.format); -} -``` - -This ensures that existing code that calls `parse()` will continue to work as expected. - -## Best Practices - -When implementing multi-file parsers: - -1. **Always mark one file as main**: Designate exactly one file as `isMain: true` to maintain backward compatibility. - -2. **Use consistent directory structure**: Follow the conventions of your target IaC format (e.g., Helm Chart layout). - -3. **Use appropriate formats**: Choose the right format for each file (YAML for Kubernetes manifests, text for template helpers, etc.). - -4. **Include descriptive comments**: Add descriptions to help users understand the purpose of each file. - -5. **Handle file dependencies**: Ensure that files reference each other correctly using relative paths. diff --git a/tmp/docker-to-iac/multi-services-support.mdx b/tmp/docker-to-iac/multi-services-support.mdx deleted file mode 100644 index cab5646..0000000 --- a/tmp/docker-to-iac/multi-services-support.mdx +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: Multi-Service Support -description: Learn about multi-service deployment support - See how docker-to-iac handles multiple services in your container configurations. -menuTitle: Multi-Service Support ---- - -# Multi-Service Support - -Multi-service support refers to the ability of a [parser](/docs/docker-to-iac/parser-explanation.md) to handle multiple container configurations when translating to Infrastructure as Code (IaC) templates. - -## Docker Run vs Docker Compose - -### Docker Run Commands - -By nature, Docker run commands define a single container. When you have multiple Docker run commands, each represents a separate service: - -```bash -# Service 1 -docker run -d -p 8080:80 nginx:alpine - -# Service 2 -docker run -d -p 6379:6379 redis:latest -``` - -### Docker Compose - -Docker Compose files can define multiple services within a single file: - -```yaml [docker-compose.yml] -version: '3.2' - -services: - web: - image: nginx:alpine - ports: - - '8080:80' - - cache: - image: redis:latest - ports: - - '6379:6379' -``` - -## Parser Support for Multiple Services - -The ability to deploy multiple services simultaneously varies by cloud provider: - -### Full Multi-Service Support - -Some cloud providers can deploy multiple containers as part of a single deployment. In these cases, docker-to-iac will translate all services to the target IaC template: - -```javascript -// All services will be included in the translation -const translation = translate(dockerComposeContent, { - source: 'compose', - target: 'CFN' // AWS CloudFormation supports multiple services -}); -``` - -### Limited Service Support - -Some providers don't support deploying multiple containers simultaneously. For these providers: - -- For Docker Compose input: Only the first service from the file will be translated -- For Docker run commands: Each command must be translated separately - -```javascript -// Only the first service will be translated -const translation = translate(dockerComposeContent, { - source: 'compose', - target: 'RND' // Render.com currently supports single service deployments -}); -``` - -## Provider-Specific Behavior - -Before using a specific parser, check its multi-service capabilities in the [parser documentation](/docs/docker-to-iac/parser-explanation.md). This helps ensure your deployment strategy aligns with the provider's capabilities. - -Note that some providers may have different service limits or deployment patterns even when they support multiple services. Always consult the target provider's documentation for specific limitations. diff --git a/tmp/docker-to-iac/parser-explanation.mdx b/tmp/docker-to-iac/parser-explanation.mdx deleted file mode 100644 index c44d5e7..0000000 --- a/tmp/docker-to-iac/parser-explanation.mdx +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: Parser Explanation -description: Understand how parsers translate Docker run commands and Docker Compose files into cloud-specific Infrastructure as Code templates. Learn about provider configurations and language support. -menuTitle: Parser Explanation ---- - -# Parser Explanation in docker-to-iac - -A parser in docker-to-iac translates Docker configurations (either Docker run commands or docker-compose.yml files) into Infrastructure as Code (IaC) or One-Click Deploy templates. Each parser is designed to target a specific IaC language or cloud provider template format. - -## Input Types - -docker-to-iac can process two types of input: - -### Docker Run Commands - -```bash -docker run -d -p 8080:80 -e NODE_ENV=production nginx:latest -``` - -### Docker Compose Files - -```yaml -version: '3' -services: - web: - image: nginx:latest - ports: - - "8080:80" - environment: - NODE_ENV: production -``` - -## API - -For detailed API documentation, see the [parser API reference](/docs/docker-to-iac/api.md). - -## Default Parser Config - -Each parser includes default configurations specific to its target cloud provider. These defaults are necessary because providers have different compute specifications and limitations. - -Example: AWS Fargate has a minimum CPU allocation of 256, while DigitalOcean's [minimum setting is 1 vCPU](https://www.digitalocean.com/pricing/app-platform). The default parser config handles these provider-specific requirements. - -To retrieve default parser configurations through the API, see the [parser info documentation](/docs/docker-to-iac/api.md#get-parser-info). - -## Parser vs. Language - -The [ParserInfo type](https://github.com/deploystackio/docker-to-iac/blob/main/src/parsers/base-parser.ts) separates variables between `Provider` and `Language`. This separation exists because some cloud providers support multiple IaC languages. - -For example, AWS infrastructure can be defined using: - -- CloudFormation -- AWS CDK (for TypeScript, Python, etc.) -- Terraform - -When adding new parsers, consider whether multiple IaC languages are possible for your target provider. This affects how you name your parser file in `src/parsers/.ts`. It's why the [`translate()`](/docs/docker-to-iac/api.md#translate-api) method requires the target IaC language name (e.g., `CFN`) rather than the provider name (e.g., `AWS`). - -## Parser Implementation Notes - -Creating parsers for multi-cloud IaC tools like Terraform presents additional challenges. Terraform's [extensive provider ecosystem](https://registry.terraform.io/browse/providers) means a Terraform parser would need complex logic to handle various provider-specific implementations, making maintenance more difficult. - -In contrast, single-provider languages like AWS CloudFormation have a one-to-one relationship with their cloud provider, simplifying parser implementation and maintenance. diff --git a/tmp/docker-to-iac/parser/aws-cloudformation.mdx b/tmp/docker-to-iac/parser/aws-cloudformation.mdx deleted file mode 100644 index 0934744..0000000 --- a/tmp/docker-to-iac/parser/aws-cloudformation.mdx +++ /dev/null @@ -1,96 +0,0 @@ ---- -title: AWS CloudFormation Parser -description: Translate docker docker-compose.yml file into AWS Cloud Formation with DeployStack -menuTitle: AWS CloudFormation ---- - -# AWS CloudFormation - Parser Full Documentation - -The parser for CloudFormation translates the `docker-compose.yml` file into CloudFormation. The parser logic can be found in GitHub inside [docker-to-iac repo](https://github.com/deploystackio/docker-to-iac/blob/main/src/parsers/aws-cloudformation.ts). - -## Parser language abbreviation for API - -- `languageAbbreviation`: `CFN`. - -## Prerequisite to deploy CloudFormation Template - -To deploy the CloudFormation template in your AWS account, you need a VPC with internet access. It should also be possible to create ENI ([AWS Elastic Network Interface](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-eni.html)) with public IP. The template uses __AWS Fargate__ without an Application Load Balancer to save costs. - -If you have the [default VPC](https://docs.aws.amazon.com/vpc/latest/userguide/default-vpc.html) in your AWS account that should be sufficient. - -## Architecture - -The architecture deploys an ECS service into a serverless [AWS Fargate](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/AWS_Fargate.html) cluster. An ECS service = service from `docker-compose.yml`. This means if you have two services in your docker-compose file, you will end up deploying two ECS services into your Fargate cluster. - -![AWS Architecture](/docs/assets/images/docker-to-iac/aws-fargate.drawio.png) - -The tasks within ECS services create an ENI that has a public IP address. Since we do not use an ALB ([Application Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/introduction.html)), you can only access the tasks via the port and the public IP address. - -When creating CloudFormation template, we decided not to use ALB to save costs. You can of course modify the CloudFormation template and add your ALB if needed. - -## Security Configuration - -### Container Security Groups - -For development and testing purposes, the template configures security groups with open TCP ports (0-65535). This configuration enables easy testing but is not recommended for production use. If you plan to use this template in production, modify the security group rules to restrict access to specific ports. - -```yaml -SecurityGroupIngress: - - IpProtocol: tcp - FromPort: 0 - ToPort: 65535 - CidrIp: 0.0.0.0/0 -``` - -### Container Root Filesystem - -To enable writes to ephemeral ECS storage, containers are configured with: - -```yaml -ReadonlyRootFilesystem: false -``` - -## Default output format - -- The default output format for this parser: `YAML`. - -## File Configuration - -The AWS CloudFormation parser generates a single consolidated template: - -- `aws-cloudformation.cf.yml` - The comprehensive CloudFormation template that defines all resources including ECS clusters, services, tasks, security groups, and IAM roles - -This single-file approach encapsulates the entire infrastructure definition in YAML format, making it ready for immediate deployment through the AWS CloudFormation console, CLI, or other AWS deployment tools. - -## Supported Docker Compose Variables - -The current version supports the following Docker Compose variables: - -For __services__: - -- image -- environment -- ports -- command - -> [!NOTE] -> The supported variables that are not on this list are ignored. This means that they are not translated by the parser in Infrastructure as Code from `docker-compose.yml` or docker run command. - -## Storage Support - -The current implementation uses ephemeral storage provided by AWS Fargate. Persistent storage solutions like EFS (Elastic File System) or EBS (Elastic Block Store) are not automatically configured due to complexity with multiple mount points and automated deployment requirements. - -For applications requiring persistent storage, consider: - -- Using external storage services (e.g., Amazon RDS for databases) -- Manually configuring EBS volumes -- Implementing a custom storage solution - -## Multi Services Support - -Multi `services` support for CloudFormation: __yes__ - -Please read more about [multi service support here](/docs/docker-to-iac/multi-services-support.md). - -> [!IMPORTANT] -> This CloudFormation template is designed for development and testing environments. For production deployments, review and adjust security groups, storage configuration, and other security settings according to your requirements. diff --git a/tmp/docker-to-iac/parser/digitalocean.mdx b/tmp/docker-to-iac/parser/digitalocean.mdx deleted file mode 100644 index 2639e2f..0000000 --- a/tmp/docker-to-iac/parser/digitalocean.mdx +++ /dev/null @@ -1,187 +0,0 @@ ---- -title: DigitalOcean Parser -description: Translate docker docker-compose.yml file into DigitalOcean Infrastructure as Code with DeployStack -menuTitle: DigitalOcean ---- - -# DigitalOcean - Parser Full Documentation - -The parser for DigitalOcean translates the `docker-compose.yml` file into a DigitalOcean [App Spec](https://docs.digitalocean.com/products/app-platform/) template. The parser logic can be found in GitHub inside the [docker-to-iac repo](https://github.com/deploystackio/docker-to-iac/blob/main/src/parsers/digitalocean.ts). - -## Parser language abbreviation for API - -- `languageAbbreviation`: `DOP`. - -## Prerequisite to deploy DigitalOcean App Spec - -To use the DigitalOcean App Spec, you need a valid DigitalOcean account with access to the App Platform and sufficient credits. - -## Architecture - -The DigitalOcean App Spec will deploy your application entirely within App Platform using containerized services: - -### App Platform Services - -Services in your App Platform deployment fall into two categories: - -#### HTTP Services - -- Web-facing containers that serve HTTP traffic -- Automatically configured with HTTPS routing: - - First service gets the root path `/` - - Additional services receive paths based on their names, e.g., `/servicename` -- Ideal for web applications, APIs, and frontend services - -#### TCP Services - -- Database containers (MySQL, PostgreSQL, Redis, etc.) run as internal TCP services -- Configured with appropriate health checks and internal ports -- No external HTTP routing - only accessible by other services within the app -- Suitable for databases, caches, and message queues - -### Important Note About Databases - -While DigitalOcean offers managed database services, these cannot be automatically provisioned through one-click deployment. Instead, database containers (like MySQL, PostgreSQL, Redis) are deployed as TCP services within App Platform, allowing: - -- Immediate deployment without pre-existing infrastructure -- Internal communication between application components -- Simplified configuration for development and testing - -For production use cases where you need managed databases, you should: - -1. Manually create managed databases in your DigitalOcean account -2. Update the application configuration to use these managed instances - -After deployment, all services can be monitored and managed through your DigitalOcean App Platform dashboard. - -## Default output format - -- The default output format for this parser: `YAML`. - -## File Configuration - -The DigitalOcean parser generates a structured output with a specific file organization: - -- `.do/deploy.template.yaml` - The main App Platform specification file that defines all services, environment variables, and configuration options for deployment - -This single-file structure follows DigitalOcean's App Platform requirements, where all deployment configurations are contained within the standard location expected by the DigitalOcean CLI and deployment tools. - -## Supported Docker Compose Variables - -This parser supports the following Docker Compose variables for services: - -- image -- environment -- ports -- command - -> [!NOTE] -> Supported variables not listed above will be ignored. They will not be translated into the Infrastructure as Code from `docker-compose.yml` or docker run command. - -## Database Support - -DigitalOcean App Platform supports running database containers as internal TCP services. The parser automatically configures these services with appropriate health checks and port settings to ensure proper communication within your application. - -### Supported Databases - -The parser recognizes and configures the following database types: - -- MySQL/MariaDB (port 3306) -- PostgreSQL (port 5432) -- Redis (port 6379) -- MongoDB (port 27017) - -### Configuration Details - -Database service configurations are defined in `src/config/digitalocean/database-types.ts`. This configuration maps Docker images to their corresponding TCP port and health check settings. - -To add or modify database configurations: - -1. Locate the `database-types.ts` file -2. Edit the `digitalOceanDatabaseConfig` object -3. Define the mapping using this structure: - -```typescript -'docker.io/library/mariadb': { - engine: 'MYSQL', - description: 'MariaDB database service - maps to MySQL managed database due to compatibility', - portNumber: 3306 -} -``` - -### Example Transformation - -Original docker-compose.yml: - -```yaml -services: - db: - image: mariadb:11.2 - environment: - MYSQL_DATABASE: myapp - app: - image: nginx:alpine - ports: - - "80:80" -``` - -Generated App Spec: - -```yaml -spec: - services: - - name: db - image: - registry_type: DOCKER_HUB - registry: library - repository: mariadb - tag: "11.2" - health_check: - port: 3306 - internal_ports: - - 3306 - - name: app - image: - registry_type: DOCKER_HUB - registry: library - repository: nginx - tag: alpine - http_port: 80 - routes: - - path: / -``` - -> [!IMPORTANT] -> While running databases as App Platform services works well for development and testing, for production workloads consider using DigitalOcean's managed database offerings for better reliability and maintenance. - -### Understanding TCP Services - -When a database image is detected, the parser: - -1. Configures the service without HTTP routing -2. Sets up appropriate internal ports for database communication -3. Adds health checks on the database's standard port -4. Ensures the service can communicate with other containers in your app - -This approach allows immediate deployment while maintaining proper isolation and communication between your application components. - -## Volume Support - -DigitalOcean App Platform supports ephemeral files only. This means: - -- No persistent volume storage is available -- Local filesystem is limited to 2GB -- Files are temporary and will be deleted after deployments or container replacements -- Each container instance has its own separate filesystem -- Changes to the filesystem are lost when instances are scaled or redeployed - -> [!WARNING] -> Any `volumes` directives in your docker-compose.yml or docker run command will be ignored during the translation to App Platform specifications. - -## Multi Services Support - -Multi `services` support for DigitalOcean: __yes__ - -DigitalOcean supports multiple services in a single App Spec file. - -Please read more about [multi service support here](/docs/docker-to-iac/multi-services-support.md). diff --git a/tmp/docker-to-iac/parser/helm.mdx b/tmp/docker-to-iac/parser/helm.mdx deleted file mode 100644 index cf50cdd..0000000 --- a/tmp/docker-to-iac/parser/helm.mdx +++ /dev/null @@ -1,211 +0,0 @@ ---- -title: Helm Parser Documentation -description: Translate Docker Compose files into Kubernetes Helm Charts with DeployStack docker-to-iac module -menuTitle: Helm ---- - -# Helm - Parser Full Documentation - -The parser for Helm translates Docker configurations into Kubernetes Helm Charts. The parser logic can be found in GitHub inside the [docker-to-iac repo](https://github.com/deploystackio/docker-to-iac/blob/main/src/parsers/helm.ts). - -## Parser language abbreviation for API - -- `languageAbbreviation`: `HELM`. - -## Prerequisite to deploy Helm Charts - -To deploy the generated Helm Charts, you need: - -- A Kubernetes cluster (local or cloud-based) -- Helm CLI installed (version 3.x recommended) -- Appropriate RBAC permissions to deploy resources in your target namespace - -### Kubernetes Resources - -The generated Helm Chart creates the following Kubernetes resources for each service in your Docker configuration: - -- **Deployments**: Container specifications, replica count, resource limits -- **Services**: Network access to your pods with appropriate ports -- **ConfigMaps**: Non-sensitive environment variables -- **Secrets**: Sensitive environment variables (passwords, tokens, etc.) - -### Database Support - -For database services, the parser leverages Helm's dependency management to incorporate official Bitnami charts: - -- **MySQL/MariaDB**: Uses Bitnami's MySQL/MariaDB chart -- **PostgreSQL**: Uses Bitnami's PostgreSQL chart -- **Redis**: Uses Bitnami's Redis chart -- **MongoDB**: Uses Bitnami's MongoDB chart - -Each database dependency is configured with appropriate defaults and includes persistent storage for data. - -## Default output format - -- The default output format for this parser: `YAML`. - -## File Configuration - -The Helm parser generates a complete Helm Chart directory structure: - -- `Chart.yaml` - The main chart definition with metadata and dependencies -- `values.yaml` - Configuration values that can be customized at deployment time -- `templates/` - Directory containing Kubernetes YAML templates: - - `deployment.yaml` - Deployment specifications for each service - - `service.yaml` - Service definitions for network access - - `configmap.yaml` - ConfigMap for non-sensitive environment variables - - `secret.yaml` - Secret for sensitive environment variables - - `_helpers.tpl` - Helper functions for template generation - - `NOTES.txt` - Usage instructions displayed after installation - -This multi-file approach follows the standard Helm Chart structure and allows for maximum flexibility when deploying to Kubernetes. - -## Supported Docker Compose Variables - -This parser supports the following Docker Compose variables: - -- `image` -- `environment` -- `ports` -- `command` -- `volumes` - -::content-alert{type="note"} -The parser automatically detects sensitive environment variables (containing keywords like "password", "secret", "key", "token", or "auth") and places them in Kubernetes Secrets instead of ConfigMaps. -:: - -## Volume Support - -The parser supports Docker volume mappings by converting them to Kubernetes volume mounts: - -- Each volume is converted to a hostPath volume by default -- Volume names are sanitized to conform to Kubernetes naming conventions -- For production use, you should modify the generated templates to use more appropriate volume types (PersistentVolumeClaims, etc.) - -## Database Integration - -When a database service is detected (MySQL, PostgreSQL, Redis, MongoDB), the parser: - -1. Adds the corresponding Bitnami Helm chart as a dependency in `Chart.yaml` -2. Configures database settings in `values.yaml` -3. Maps environment variables to the expected format for the database chart -4. Sets up appropriate persistence configurations - -### Example Database Configuration - -For a PostgreSQL database in your Docker Compose file: - -```yaml -services: - db: - image: postgres:13 - environment: - POSTGRES_USER: myuser - POSTGRES_PASSWORD: mypassword - POSTGRES_DB: myapp -``` - -The parser will create: - -```yaml -# In Chart.yaml -dependencies: - - name: db - repository: https://charts.bitnami.com/bitnami - version: ^12.0.0 - condition: dependencies.db.enabled - -# In values.yaml -dependencies: - db: - enabled: true - auth: - postgres: - password: mypassword - database: myapp - username: myuser - password: mypassword - primary: - service: - ports: - postgresql: 5432 - persistence: - enabled: true - size: 8Gi -``` - -## Service Connections - -The parser supports service-to-service connections by leveraging Kubernetes DNS for service discovery. When a service refers to another service in an environment variable, the parser automatically configures the appropriate DNS references. - -For example, if your `app` service connects to a `db` service: - -```yaml -# Docker Compose -services: - app: - image: myapp - environment: - DATABASE_URL: postgresql://postgres:password@db:5432/mydb - - db: - image: postgres - environment: - POSTGRES_PASSWORD: password - POSTGRES_DB: mydb -``` - -The parser will create: - -```yaml -# In ConfigMap template -data: - DATABASE_URL: {{ include "deploystack.serviceReference" (dict "service" (index $.Values.services "db") "serviceKey" "db") }} -``` - -Which resolves to the Kubernetes DNS name: `db.{{ .Release.Namespace }}.svc.cluster.local:5432` - -## Multi Services Support - -Multi `services` support for Helm: **yes** - -Helm Charts are designed to handle multiple services and dependencies in a single deployment, making them ideal for complex applications. The parser transforms all services from your Docker Compose file into corresponding Kubernetes resources. - -Please read more about [multi service support here](/docs/docker-to-iac/multi-services-support.md). - -## Deployment Instructions - -To deploy the generated Helm Chart: - -1. Navigate to the directory containing the generated chart -2. Install dependencies: - - ```bash - helm dependency update - ``` - -3. Install the chart: - - ```bash - helm install my-release . - ``` - -4. For custom configurations: - - ```bash - helm install my-release . --set services.app.replicaCount=2 - ``` - -## Production Considerations - -For production deployments, consider the following modifications to the generated chart: - -1. Replace hostPath volumes with appropriate persistent volume claims -2. Adjust resource limits in `values.yaml` -3. Configure proper ingress settings for external access -4. Enable and configure horizontal pod autoscaling -5. Set up proper liveness and readiness probes - -::content-alert{type="important"} -The generated Helm Chart is a starting point that you should review and customize to match your production requirements and security best practices. -:: diff --git a/tmp/docker-to-iac/parser/index.mdx b/tmp/docker-to-iac/parser/index.mdx deleted file mode 100644 index 87c45ce..0000000 --- a/tmp/docker-to-iac/parser/index.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Available parsers -description: View all available parsers in docker-to-iac for converting Docker Compose to cloud infrastructure templates. Supports major cloud providers. -menuTitle: Available parser ---- - -# Available parser list for module docker-to-iac - -Here you can find the list of available [parsers](/docs/docker-to-iac/parser-explanation.md): - -- [AWS CloudFormation](/docs/docker-to-iac/parser/aws-cloudformation.md) -- [Render.com](/docs/docker-to-iac/parser/render.com.md) -- [DigitalOcean](/docs/docker-to-iac/parser/digitalocean.md) -- [Helm (Kubernetes)](/docs/docker-to-iac/parser/helm.md) diff --git a/tmp/docker-to-iac/parser/render.com.mdx b/tmp/docker-to-iac/parser/render.com.mdx deleted file mode 100644 index 42f5c4e..0000000 --- a/tmp/docker-to-iac/parser/render.com.mdx +++ /dev/null @@ -1,133 +0,0 @@ ---- -title: Render.com - Parser Full Documentation -description: Translate docker docker-compose.yml file into Render.com Infrastructure as Code with DeployStack -menuTitle: Render.com ---- - -# Render.com - Parser Full Documentation - -The parser for Render.com translates the `docker-compose.yml` file into Render [BluePrint](https://render.com/docs/infrastructure-as-code). The parser logic can be found in GitHub inside [docker-to-iac repo](https://github.com/deploystackio/docker-to-iac/blob/main/src/parsers/render.ts). - -## Parser language abbreviation for API - -- `languageAbbreviation`: `RND`. - -## Prerequisite to deploy Render BluePrint - -There are no special requirements for using the Render.com blueprint. However, you need a valid render.com account with sufficient credits. - -## Architecture - -The BluePrint will create a render "web" service. - -Type = "[Web Service](https://render.com/docs/blueprint-spec#type)". - -Render dashboard will list all your web services. At the top, you can switch between Dashboard and BluePrints. - -![Render BluePrints](/docs/assets/images/docker-to-iac/render.com-dashboard-blueprints.png) - -After the BluePrint has been created through one-click deployment, the BluePrint will be visible in the BluePrint menu. - -In contrast to other cloud providers, Render.com's usability is very trivial. There is no VPC / VNet or anything else. After successful deployment, you can open your service via a URL. - -## Default output format - -- The default output format for this parser: `YAML`. - -## File Configuration - -The Render.com parser generates a single file output: - -- `render.yaml` - The main Blueprint configuration file that defines all services, environment variables, and disk configurations - -This straightforward single-file approach aligns with Render's Blueprint specification, which requires all service definitions to be contained within a single YAML file. The file is structured according to Render's requirements with services, environment variables, and disk configurations properly organized for immediate deployment. - -## Supported Docker Compose Variables - -The current version supports the following Docker Compose variables: - -For __services__: - -- image -- environment -- ports -- command - -> [!NOTE] -> The supported variables that are not on this list are ignored. This means that they are not translated by the parser in Infrastructure as Code from `docker-compose.yml` or docker run command. - -## Volume Support - -Render.com offers two types of storage options: - -### Default: Ephemeral Filesystem - -By default, Render services use an ephemeral filesystem where: - -- Changes to the filesystem are lost after deployments or restarts -- Each service instance has its own separate filesystem -- No data persists between deployments - -### Persistent Disk Option - -The parser supports adding persistent disk storage through the `volumes` directive: - -- Persistent disks are automatically configured with 10GB size -- Only one disk per service is supported -- Files are preserved across deployments and restarts -- Only filesystem changes under the disk's mount path are preserved - -Important limitations for persistent disks: - -- A disk can only be accessed by a single service instance -- Services with persistent disks cannot scale to multiple instances - -Read more here: [render.com/docs/disks](https://render.com/docs/disks) - -## Service Types - -The parser automatically determines the appropriate service type for each container in your Docker configuration: - -### Web Services (Default) - -By default, services are created as `type: web`, which is suitable for: - -- HTTP-based applications -- Frontend applications -- API servers -- Any service that needs to be publicly accessible - -### Private Services - -For databases and other TCP-based services, the parser automatically sets `type: pserv`. These services: - -- Are not publicly accessible -- Can communicate with other services over TCP -- Are ideal for databases and backend services - -Read more here: [render.com/docs/private-services](https://render.com/docs/private-services). - -The service type is determined based on the Docker image being used. For example: - -```yaml -services: - web: - image: nginx:latest - # Automatically set to type: web - - db: - image: mariadb:11.2 - # Automatically set to type: pserv -``` - -### Adding New Service Types - -If you're using a service that should be private but isn't automatically detected, please visit our [Render: Contributing to Render Service Types docs page](/docs/docker-to-iac/render-contributing-to-service-types.md). - -## Multi Services Support - -Multi `services` support for Render.com: __yes__ - -Since [multi services](https://render.com/docs/blueprint-spec#root-level-fields) feature is supported. - -Please read more about [multi service support here](/docs/docker-to-iac/multi-services-support.md). diff --git a/tmp/docker-to-iac/project-structure.mdx b/tmp/docker-to-iac/project-structure.mdx deleted file mode 100644 index 4d2fd2e..0000000 --- a/tmp/docker-to-iac/project-structure.mdx +++ /dev/null @@ -1,176 +0,0 @@ ---- -title: Project Structure -description: Directory structure and organization of the docker-to-iac module, including guidance for adding new parsers, source handlers, and tests. -menuTitle: Project Structure ---- - -# Project Structure of docker-to-iac Module - -The project follows standard npm module organization with a well-defined structure to handle both Docker run commands and Docker Compose files, supporting multiple output formats and comprehensive testing. - -## Directory Structure - -```bash -docker-to-iac/ -|-- src/ # Source code -| |-- index.ts # Main entry point -| |-- config/ # Provider-specific configurations -| | |-- connection-properties.ts -| | |-- digitalocean/ -| | | |-- database-types.ts -| | |-- render/ -| | |-- service-types.ts -| |-- parsers/ # IaC parsers for different cloud providers -| | |-- aws-cloudformation.ts -| | |-- base-parser.ts -| | |-- digitalocean.ts -| | |-- render.ts -| |-- sources/ # Input source handlers -| | |-- base.ts -| | |-- factory.ts -| | |-- compose/ # Docker Compose handling -| | | |-- index.ts -| | | |-- validate.ts -| | |-- run/ # Docker run command handling -| | |-- index.ts -| |-- types/ # TypeScript type definitions -| | |-- container-config.ts -| | |-- environment-config.ts -| | |-- service-connections.ts -| |-- utils/ # Helper utilities -| |-- constructImageString.ts -| |-- detectDatabaseEnvVars.ts -| |-- digitalOceanParserServiceName.ts -| |-- getDigitalOceanDatabaseType.ts -| |-- getImageUrl.ts -| |-- parseCommand.ts -| |-- parseDockerImage.ts -| |-- parseEnvFile.ts -| |-- processEnvironmentVariablesGeneration.ts -| |-- resolveEnvironmentValue.ts -| |-- (... and many more) -|-- test/ # Test files -| |-- e2e/ # End-to-end tests -| | |-- assertions/ # Test assertions -| | | |-- digitalocean.ts -| | | |-- do-port-assertions.ts -| | | |-- port-assertions.ts -| | | |-- render.ts -| | |-- docker-compose-files/ # Test Docker Compose files -| | |-- docker-run-files/ # Test Docker run commands -| | |-- output/ # Test output directory -| | |-- utils/ # Test utilities -| | |-- index.ts # Main E2E test executor -| | |-- test1.ts # Environment variables and volume mapping tests -| | |-- test2.ts # Port mapping tests -| | |-- test3.ts # Environment variable substitution tests -| | |-- test4.ts # Schema validation tests -| |-- unit/ # Unit tests -| | |-- config/ # Configuration tests -| | |-- parsers/ # Parser tests -| | |-- sources/ # Source handler tests -| | |-- utils/ # Utility function tests -| |-- test.ts # Main test entry point -|-- eslint.config.mjs # ESLint configuration -|-- tsconfig.json # TypeScript configuration -|-- vitest.config.ts # Vitest configuration -|-- package.json # Package configuration -|-- README.md # Project documentation -``` - -## Directory Purposes - -### Core Directories - -- `src/` - Source code for the module -- `test/` - Test files organized by test type (unit and end-to-end) -- `dist/` - Compiled output (generated during build) - -### Source Code Organization - -#### Config (`src/config/`) - -Contains provider-specific configurations: - -- `connection-properties.ts` - Cross-provider connection property mappings -- `digitalocean/` - DigitalOcean App Platform specific configurations - - `database-types.ts` - Database type mappings for DigitalOcean -- `render/` - Render.com specific configurations - - `service-types.ts` - Service type mappings for Render deployments - -#### Parsers (`src/parsers/`) - -Contains IaC-specific parsers for different cloud providers: - -- `base-parser.ts` - Base parser class that defines common functionality -- `aws-cloudformation.ts` - AWS CloudFormation parser -- `digitalocean.ts` - DigitalOcean App Platform parser -- `render.ts` - Render Blueprint parser -- ... additional parsers for other providers - -#### Source Handlers (`src/sources/`) - -Handles different input types: - -- `base.ts` - Base source handler interface -- `factory.ts` - Factory for creating appropriate source handlers -- `compose/` - Docker Compose file processing - - `index.ts` - Main Compose parser - - `validate.ts` - Compose file validation -- `run/` - Docker run command processing - - `index.ts` - Docker run command parser - -#### Types (`src/types/`) - -TypeScript type definitions: - -- `container-config.ts` - Container and service configuration types -- `environment-config.ts` - Environment variable configuration types -- `service-connections.ts` - Service connection configuration types - -#### Utilities (`src/utils/`) - -Helper functions for parsing and processing: - -- `constructImageString.ts` - Docker image string construction -- `detectDatabaseEnvVars.ts` - Database environment variable detection -- `digitalOceanParserServiceName.ts` - Name formatting for DigitalOcean -- `getDigitalOceanDatabaseType.ts` - Database type detection for DigitalOcean -- `parseDockerImage.ts` - Docker image parsing -- `parseEnvFile.ts` - Environment file parsing -- `resolveEnvironmentValue.ts` - Environment variable resolution -- And many more utility functions for specific operations - -### Test Organization - -#### End-to-End Tests (`test/e2e/`) - -Integration tests that validate the complete workflow: - -- `assertions/` - Validation functions for test output -- `docker-compose-files/` - Test Docker Compose files -- `docker-run-files/` - Test Docker run commands -- `output/` - Generated test outputs -- `utils/` - Test helper utilities -- `test1.ts` through `test4.ts` - Specific test scenarios: - 1. Environment variables and volume mapping - 2. Port mappings - 3. Environment variable substitution - 4. Schema validation - -#### Unit Tests (`test/unit/`) - -Tests for individual components: - -- `config/` - Tests for configuration modules -- `parsers/` - Tests for IaC parsers -- `sources/` - Tests for source handlers -- `utils/` - Tests for utility functions - -## Adding New Parser - -Please check our [Adding a New Parser](/docs/docker-to-iac/example-of-a-new-parser.md) documentation for detailed instructions on how to add a new parser to the project. This includes creating a new parser file, implementing the parsing logic, and ensuring compatibility with existing configurations. - -### Adding New Tests - -Please refer to the [Testing](/docs/docker-to-iac/testing.md) documentation for guidelines on adding new tests, including unit and end-to-end tests. diff --git a/tmp/docker-to-iac/publishing-to-npm.mdx b/tmp/docker-to-iac/publishing-to-npm.mdx deleted file mode 100644 index b67d68e..0000000 --- a/tmp/docker-to-iac/publishing-to-npm.mdx +++ /dev/null @@ -1,84 +0,0 @@ ---- -title: Publishing docker-to-iac to NPM -description: Explore our automated NPM publishing workflow for docker-to-iac. From preparing a release branch to package deployment, understand our conventional commits-based process. -menuTitle: Publishing to NPM ---- - -# Publishing docker-to-iac module to NPM - -We have created an organization @deploystack for NPM. Publishing in NPM happens automatically through `semantic-release`. Config: [https://github.com/deploystackio/docker-to-iac/blob/main/.github/workflows/release-pr.yml](https://github.com/deploystackio/docker-to-iac/blob/main/.github/workflows/release-pr.yml) - -## Release Process Overview - -The release process follows these steps: - -1. Initiate a release preparation using the GitHub workflow -2. Review and merge the release pull request -3. Automatic publishing to NPM when the release PR is merged - -## Starting a Release - -Releases can be initiated through the GitHub Actions UI: - -1. Navigate to the "Actions" tab in the repository -2. Select the "Release Process" workflow -3. Click "Run workflow" -4. Choose the release type: - - `patch` (bug fixes) - - `minor` (new features) - - `major` (breaking changes) -5. Optionally select "Prerelease" for beta versions -6. Click "Run workflow" - -## What Happens During Release Preparation - -The workflow performs the following steps: - -1. Updates the version in package.json based on conventional commits -2. Updates the CHANGELOG.md file with details of changes since the last release -3. Creates a new branch with these changes (named `release-v{version}`) -4. Provides a link to create a pull request - -## Creating the Pull Request - -After the workflow completes: - -1. Follow the link provided in the workflow output to create a pull request -2. **Important**: Add the `release` label to your pull request -3. Request a review of the PR - -## Publishing Process - -When the pull request with the `release` label is merged: - -1. The GitHub Action automatically creates a Git tag for the new version -2. A GitHub release is created with the changelog contents -3. The package is built using `npm run build` -4. The package is published to NPM with public access - -## Npm Package - -The published package is available at: [https://www.npmjs.com/package/@deploystack/docker-to-iac](https://www.npmjs.com/package/@deploystack/docker-to-iac) - -## Conventional Commits - -The project uses conventional commits to determine version bumps and generate changelogs. Commit messages should follow this pattern: - -- `feat: ...` - A new feature (minor version bump) -- `fix: ...` - A bug fix (patch version bump) -- `chore: ...` - Maintenance changes -- `docs: ...` - Documentation changes -- `style: ...` - Code style changes -- `refactor: ...` - Code refactoring -- `perf: ...` - Performance improvements -- `test: ...` - Test updates - -Breaking changes should include `BREAKING CHANGE:` in the commit message body or footer. - -## Configuration Files - -The release process is configured through several files: - -- `.github/workflows/release-pr.yml` - GitHub Actions workflow -- `.release-it.js` - Configuration for release-it -- `package.json` - NPM scripts for the release process diff --git a/tmp/docker-to-iac/quickstart.mdx b/tmp/docker-to-iac/quickstart.mdx deleted file mode 100644 index 2d3ed07..0000000 --- a/tmp/docker-to-iac/quickstart.mdx +++ /dev/null @@ -1,65 +0,0 @@ ---- -title: Quickstart Guide -description: Quickstart guide for using docker-to-iac to translate Docker run commands and Docker Compose files into infrastructure as code templates -menuTitle: Quickstart ---- - -# Quickstart Guide - -## Installation - -First, install the module and its dependencies: - -```bash -npm i @deploystack/docker-to-iac -``` - -## Usage Examples - -### Translating Docker Compose - -```javascript -import { translate } from '@deploystack/docker-to-iac'; -import { readFileSync, writeFileSync } from 'fs'; - -// Read Docker Compose file content -const dockerComposeContent = readFileSync('path/to/docker-compose.yml', 'utf8'); - -const translatedConfig = translate(dockerComposeContent, { - source: 'compose', - target: 'CFN', - templateFormat: 'yaml' -}); - -// Write the translated config to a file -writeFileSync('output-aws.yml', translatedConfig); -``` - -### Translating Docker Run Commands - -```javascript -import { translate } from '@deploystack/docker-to-iac'; -import { writeFileSync } from 'fs'; - -// Your docker run command -const dockerRunCommand = 'docker run -d -p 8080:80 -e NODE_ENV=production nginx:latest'; - -const translatedConfig = translate(dockerRunCommand, { - source: 'run', - target: 'CFN', - templateFormat: 'yaml' -}); - -// Write the translated config to a file -writeFileSync('output-aws.yml', translatedConfig); -``` - -### Translation Options - -When using the `translate` function, you can specify: - -- `source`: Either 'compose' or 'run' depending on your input -- `target`: The IaC language to translate to (e.g., 'CFN' for AWS CloudFormation) -- `templateFormat`: Output format - 'json', 'yaml', or 'text' - -For a complete list of supported parsers and formats, visit the [API documentation](/docs/docker-to-iac/api.md). diff --git a/tmp/docker-to-iac/render-contributing-to-service-types.mdx b/tmp/docker-to-iac/render-contributing-to-service-types.mdx deleted file mode 100644 index 11eade0..0000000 --- a/tmp/docker-to-iac/render-contributing-to-service-types.mdx +++ /dev/null @@ -1,147 +0,0 @@ ---- -title: Contributing to Render Service Types -description: Guide for contributing to Render.com service type configurations in docker-to-iac -menuTitle: Render Service Types Contributing ---- - -# Render: Contributing to Render Service Types - -This guide explains how to contribute to the Render.com service type configurations in docker-to-iac. The service types configuration determines whether a Docker service should be deployed as a web service, private service, or Redis service on Render.com. - -## Configuration Location - -The service types configuration is stored in: - -```bash -src/config/render/service-types.ts -``` - -This configuration is specific to Render.com and is not used by other cloud provider parsers. - -## TypeScript Configuration Structure - -The configuration uses the following structure: - -```typescript -interface ServiceTypeConfig { - type: string; - description: string; - versions: string; -} - -interface RenderServiceTypesConfig { - serviceTypes: { - [key: string]: ServiceTypeConfig; - }; -} - -export const renderServiceTypesConfig: RenderServiceTypesConfig = { - serviceTypes: { - 'docker.io/library/mariadb': { - type: 'pserv', - description: 'MariaDB database service - requires private service type due to TCP protocol', - versions: '*' - } - } -}; -``` - -### Field Definitions - -- `serviceTypes`: Root object containing all service type mappings -- Image key (e.g., `docker.io/library/mariadb`): The fully qualified Docker image name - - Should match the normalized format from `getImageUrl` utility - - For official Docker Hub images, use `docker.io/library/[name]` - - For user repositories, use `docker.io/[user]/[repo]` - - For GHCR, use `ghcr.io/[owner]/[repo]` -- `type`: The Render service type - - `pserv` for private services (databases, message queues, etc.) - - `web` is the default and doesn't need to be specified -- `description`: A clear explanation of why this service type is needed -- `versions`: Version matching pattern - - Use `"*"` for all versions - - Future: Will support semantic version ranges - -## Contributing Guidelines - -1. Identify the Need - - Service fails when deployed as `web` type - - Service requires TCP/private networking - - Service is a database or backend service - -2. Determine the Correct Image Name - - ```typescript - // Use the getImageUrl utility to find the correct name format - const imageUrl = getImageUrl('mysql:5.7'); - // Returns: docker.io/library/mysql - ``` - -3. Add Your Configuration - - Add a new entry to the `renderServiceTypesConfig` object - - Include a descriptive comment explaining the service type choice - - Follow the TypeScript interface structure shown above - -4. Submit a Pull Request - - Fork the repository - - Add your changes to `service-types.ts` - - Create a pull request with: - - Clear description of the service - - Why it needs a specific service type - - Any relevant documentation links - -## Example Addition - -Here's an example of a good service type addition: - -```typescript -export const renderServiceTypesConfig: RenderServiceTypesConfig = { - serviceTypes: { - // Existing configurations... - 'docker.io/library/postgresql': { - type: 'pserv', - description: 'PostgreSQL database service - requires private networking for security', - versions: '*' - }, - 'docker.io/library/rabbitmq': { - type: 'pserv', - description: 'RabbitMQ message broker - requires private TCP communication', - versions: '*' - } - } -}; -``` - -## Service Type Categories - -### Private Services (`pserv`) - -Common services that should use `pserv`: - -- Databases (MySQL, PostgreSQL, MongoDB) -- Message queues (RabbitMQ, Apache Kafka) -- Cache services (except Redis) -- Backend services that don't serve HTTP traffic - -### Web Services (`web`) - -Services that should remain as default `web` type: - -- HTTP APIs -- Web applications -- Frontend services -- Application servers - -## Getting Help - -If you're unsure about: - -- Which service type to use -- How to format the image name -- Whether a service needs a specific type - -Please: - -- Check Render's [service types documentation](https://render.com/docs/blueprint-spec#type) -- Open a discussion in our feedback GitHub repository [github.com/deploystackio/feedback](https://github.com/deploystackio/feedback) -- Join our [Discord community](https://discord.gg/UjFWwByB) for help diff --git a/tmp/docker-to-iac/service-connections.mdx b/tmp/docker-to-iac/service-connections.mdx deleted file mode 100644 index 8018c73..0000000 --- a/tmp/docker-to-iac/service-connections.mdx +++ /dev/null @@ -1,227 +0,0 @@ ---- -title: Service Connections in docker-to-iac -description: Configure service-to-service communication in multi-container applications with docker-to-iac's service connections feature. Transform Docker Compose service references to cloud provider formats. -menuTitle: Service Connections ---- - -# Service Connections - -The `docker-to-iac` module supports configuring service-to-service communication when translating Docker Compose files to cloud provider IaC templates. This feature is essential for multi-container applications where services need to communicate with each other (e.g., web applications connecting to databases). - -## The Challenge - -In Docker Compose, services can communicate with each other using the service name as the hostname: - -```yaml -# docker-compose.yml -services: - db: - image: mariadb:latest - # ... - - app: - image: myapp:latest - environment: - - DATABASE_HOST=db # Reference to the db service - - API_URL=http://api:3000 # Reference within a URL - # ... -``` - -However, when deploying to cloud providers, each has its own format for service discovery: - -- **Render.com**: Uses Blueprint's `fromService` syntax for service references -- **DigitalOcean App Platform**: Services connect using the service name directly - -The Service Connections feature automatically configures these references based on the target cloud provider. - -## Supported Providers - -Currently, service connections are supported for: - -| Provider | Implementation | Example Reference | -|----------|---------------|------------------| -| Render.com | Blueprint's `fromService` | `fromService: { name: "db", type: "web", property: "hostport" }` | -| DigitalOcean App Platform | Direct service name | `db` or `http://api:3000` | - -> **Note**: AWS CloudFormation is not supported for service connections as it does not provide a direct way to reference services by name across tasks in the generated architecture. - -## Usage - -To configure service connections, use the `serviceConnections` option in the `translate` function: - -```javascript -import { translate } from '@deploystack/docker-to-iac'; - -const result = translate(dockerComposeContent, { - source: 'compose', - target: 'RND', // Or 'DOP' - templateFormat: 'yaml', - serviceConnections: { - mappings: [ - { - fromService: 'app', // Service that needs to connect - toService: 'db', // Service to connect to - environmentVariables: [ // List of env vars that reference the service - 'DATABASE_HOST', - 'API_URL' - ], - property: 'connectionString' // The type of connection (connectionString, hostport, etc.) - } - ] - } -}); -``` - -### Configuration Options - -For each service connection mapping: - -- `fromService`: The service that needs to connect to another service -- `toService`: The service being connected to -- `environmentVariables`: Array of environment variable names that reference the target service -- `property`: The type of connection property to reference (e.g., 'connectionString', 'hostport', etc.) - -## Provider-Specific Implementations - -### Render.com - -For Render.com, the module generates Blueprint configurations using the native `fromService` syntax: - -```yaml -# Generated Render Blueprint -services: - - name: app - # ...other configuration... - envVars: - # Regular environment variables - - key: NODE_ENV - value: production - - # Service reference using fromService - - key: DATABASE_HOST - fromService: - name: db - type: pserv - property: hostport # This property is derived from the 'property' parameter in your mapping -``` - -This approach leverages Render's built-in service discovery capabilities for reliable inter-service communication. - -### DigitalOcean App Platform - -For DigitalOcean App Platform, the module maintains the direct service name references, as services can communicate directly using the service name: - -```yaml -# Generated DigitalOcean App Spec -services: - - name: app - # ...other configuration... - envs: - - key: DATABASE_HOST - value: db - - key: API_URL - value: http://api:3000 -``` - -## Complete Example - -Here's a complete example showing Node.js microservices communicating with each other, and a more detailed database connection example: - -```javascript -const dockerComposeContent = ` -version: "3" - -services: - api: - image: node:18-alpine - command: node /app/server.js - ports: - - "3000:3000" - - frontend: - image: node:18-alpine - environment: - - API_URL=http://api:3000 # This will be transformed appropriately - ports: - - "8080:8080" -`; - -const serviceConnections = { - mappings: [ - { - fromService: 'frontend', - toService: 'api', - environmentVariables: ['API_URL'], - property: 'hostport' - } - ] -}; - -// For DigitalOcean - Service name stays as "api" in http://api:3000 -// For Render - Will use fromService syntax instead of string replacement - -// Database Connection Example -const databaseComposeContent = ` -services: - app: - image: node:18-alpine - environment: - - DATABASE_URL=postgresql://postgres:secret@postgres:5432/mydb - ports: - - "3000:3000" - - postgres: - image: postgres:latest - environment: - - POSTGRES_DB: mydb - - POSTGRES_USER: postgres - - POSTGRES_PASSWORD: secret -`; - -const dbServiceConnections = { - mappings: [ - { - fromService: 'app', - toService: 'postgres', - environmentVariables: ['DATABASE_URL'], - property: 'connectionString' // Use connectionString for full database URL - } - ] -}; - -// Result will include proper connection format for each provider -// DigitalOcean: DATABASE_URL=${postgres.DATABASE_URL} -// Render: fromDatabase: { name: "postgres", property: "connectionString" } -``` - -## Response Format - -The `translate` function returns information about the resolved service connections: - -```javascript -{ - files: { - // Generated IaC template files - }, - serviceConnections: [ - { - fromService: 'app', - toService: 'db', - variables: { - 'DATABASE_HOST': { - originalValue: 'db', - transformedValue: 'db' // For DigitalOcean or Render - } - } - } - ] -} -``` - -This information can be useful for debugging or understanding how service connections were processed. - -## Limitations - -- The feature only transforms environment variable values that exactly match the service name -- More complex connection strings must be handled separately -- The feature doesn't adjust ports or protocols, only service hostnames diff --git a/tmp/docker-to-iac/supported-docker-compose-variables.mdx b/tmp/docker-to-iac/supported-docker-compose-variables.mdx deleted file mode 100644 index b4e5e50..0000000 --- a/tmp/docker-to-iac/supported-docker-compose-variables.mdx +++ /dev/null @@ -1,84 +0,0 @@ ---- -title: Supported Docker Compose Variables -description: Detailed reference for Docker Compose variables compatible with docker-to-iac translations. Find supported service properties, registry options, and configuration examples for successful IaC deployments. -menuTitle: Docker Compose Variables ---- - -# Supported Docker Compose Variables - -This document outlines all the Docker Compose variables that are currently supported by the docker-to-iac module when translating your docker-compose.yml file into Infrastructure as Code templates. - -## Core Requirements - -The docker-to-iac module requires that your docker-compose.yml file meets these basic requirements: - -1. The file must contain at least one service -2. Each service must specify an `image` property (build instructions are not supported) - -## Supported Service Properties - -For each service in your docker-compose.yml file, the following properties are supported: - -### Required Properties - -| Property | Description | Example | -|----------|-------------|----------| -| `image` | The Docker image to use for the service. Must be a pre-built image available in a public registry. | `image: nginx:latest` | - -### Optional Properties - -| Property | Description | Example | -|----------|-------------|----------| -| `ports` | List of ports to expose. Supports port mapping in standard Docker format. | `ports:`
` - "8080:80"`
` - "443:443"` | -| `command` | Override the default command of the Docker image. | `command: "npm start"` | -| `restart` | Container restart policy. | `restart: always` | -| `volumes` | List of volume mappings. | `volumes:`
` - "data:/var/lib/mysql"`
` - "./config:/etc/nginx/conf.d:ro"` | -| `environment` | Environment variables as key-value pairs. | `environment:`
` NODE_ENV: production`
` PORT: 3000` | - -## Example Configuration - -Here's a complete example showing all supported variables: - -```yaml -services: - web: - image: nginx:alpine - ports: - - "80:80" - - "443:443" - command: "nginx -g 'daemon off;'" - restart: always - volumes: - - ./nginx.conf:/etc/nginx/nginx.conf:ro - environment: - NGINX_HOST: example.com - NGINX_PORT: 80 - - api: - image: node:16-alpine - ports: - - "3000:3000" - command: "npm start" - restart: always - environment: - NODE_ENV: production - DATABASE_URL: mongodb://db:27017/myapp -``` - -## Important Notes - -1. Build instructions (`build:`) are not supported - you must use pre-built images -2. Services must use images that are publicly accessible -3. Each service must have an `image` property specified -4. Environment variables should not contain sensitive information as they will be included in the generated IaC templates -5. Volume definitions are supported but their implementation may vary depending on the target cloud platform - -## Validation - -The module performs validation checks to ensure: - -- The docker-compose.yml file contains at least one service -- Each service has an `image` property specified -- The Docker image reference is valid and follows the expected format - -If validation fails, the module will throw a `DockerComposeValidationError` with a descriptive message explaining the issue. diff --git a/tmp/docker-to-iac/supported-registries.mdx b/tmp/docker-to-iac/supported-registries.mdx deleted file mode 100644 index 5ba1e77..0000000 --- a/tmp/docker-to-iac/supported-registries.mdx +++ /dev/null @@ -1,84 +0,0 @@ ---- -title: Supported Registries -description: Complete guide to Docker registries in docker-to-iac - From official Docker Hub images to GHCR, learn supported formats with practical examples. -menuTitle: Supported Registries ---- - -# Supported Registries for docker-to-iac module - -docker-to-iac supports multiple Docker image registries. Below you'll find details about supported registries and examples of how they are handled. - -## Docker Hub Registry - -Docker Hub is the default and most common registry for Docker images. - -### Official Images - -Docker Hub official images are maintained by Docker and don't include a username/organization prefix. - -**Docker Compose Example:** - -```yaml -services: - db: - image: redis:latest -``` - -**Translated Image URL:** - -```text -docker.io/library/redis:latest -``` - -### User/Organization Images - -Docker Hub images that belong to specific users or organizations include the username/organization as prefix. - -**Docker Compose Example:** - -```yaml -services: - app: - image: nginx/nginx-prometheus-exporter:0.10.0 -``` - -**Translated Image URL:** - -```text -docker.io/nginx/nginx-prometheus-exporter:0.10.0 -``` - -## GitHub Container Registry (GHCR) - -GitHub Container Registry is GitHub's container registry service that allows you to host and manage Docker container images. - -**Docker Compose Example:** - -```yaml -services: - monitor: - image: ghcr.io/dgtlmoon/changedetection.io -``` - -**Translated Image URL:** - -```text -ghcr.io/dgtlmoon/changedetection.io -``` - -## Registry URL Formats - -Here's how different registry types are handled: - -| Registry Type | Format | Example | -|--------------|--------|---------| -| Docker Hub (Official) | docker.io/library/[image]:[tag] | docker.io/library/redis:latest | -| Docker Hub (User) | docker.io/[user]/[image]:[tag] | docker.io/nginx/nginx-prometheus-exporter:0.10.0 | -| GitHub Container Registry | ghcr.io/[user]/[image]:[tag] | ghcr.io/dgtlmoon/changedetection.io | - -## Notes - -- If no tag is specified, `latest` is used as the default tag -- The module preserves the original registry URL format for custom registries -- SHA256 digests are supported for all registry types -- All supported registries work with all parsers, including AWS CloudFormation, Render.com, DigitalOcean App Platform, and Kubernetes Helm Charts diff --git a/tmp/docker-to-iac/testing.mdx b/tmp/docker-to-iac/testing.mdx deleted file mode 100644 index fdc8e77..0000000 --- a/tmp/docker-to-iac/testing.mdx +++ /dev/null @@ -1,328 +0,0 @@ ---- -title: Testing docker-to-iac Module -description: Learn how to test the docker-to-iac module including Docker run commands and Docker Compose files, with support for integration and end-to-end testing. -menuTitle: Testing ---- - -# Testing docker-to-iac Module - -Before submitting a pull request, test your code locally. Testing covers both code quality and functional aspects for Docker run commands and Docker Compose files, including multi-file output capabilities and cross-platform compatibility. - -## Running Tests - -### Code Quality Check - -First, run ESLint to ensure code quality: - -```bash -npm run lint -``` - -ESLint must pass locally before submitting your PR, as GitHub Actions CI/CD will block any PR that fails the lint check. - -### Unit Testing - -To run unit tests only: - -```bash -npm run test:unit -``` - -Unit tests verify individual functions and components work correctly in isolation. - -### End-to-End Testing - -To run end-to-end tests only: - -```bash -npm run test:e2e -``` - -End-to-end tests validate the entire translation process with real inputs and outputs. - -### All Tests - -Run the complete test suite: - -```bash -npm run test -``` - -This will execute both unit tests and end-to-end tests to ensure comprehensive coverage. - -## Test Suite Structure - -The test suite is organized in a hierarchical structure: - -```bash -test/ -├── e2e/ # End-to-end tests -│ ├── assertions/ # Testing assertions for output validation -│ │ ├── digitalocean.ts # DigitalOcean-specific assertions -│ │ ├── do-port-assertions.ts -│ │ ├── port-assertions.ts -│ │ └── render.ts # Render-specific assertions -│ ├── docker-compose-files/ # Test docker-compose files -│ │ ├── test1.yml -│ │ ├── test2.yml -│ │ └── ... -│ ├── docker-run-files/ # Test docker run commands -│ │ ├── test1.txt -│ │ ├── test2.txt -│ │ └── ... -│ ├── output/ # Generated test outputs -│ │ └── README.md # Explanation of the output directory -│ ├── utils/ # Testing utilities -│ ├── index.ts # Main e2e test executor -│ ├── test1.ts # Environment variables and volume mapping tests -│ ├── test2.ts # Port mapping tests -│ ├── test3.ts # Environment variable substitution tests -│ └── test4.ts # Render-specific validation -├── unit/ # Unit tests -│ ├── config/ # Tests for configuration -│ ├── parsers/ # Tests for parsers -│ ├── sources/ # Tests for sources -│ └── utils/ # Tests for utility functions -└── test.ts # Main test file -``` - -## End-to-End Test Scenarios - -The end-to-end tests cover four main scenarios: - -### Test 1: Environment Variables and Volume Mapping - -Tests the translation of environment variables and volume mappings for both Docker run commands and Docker Compose files. It verifies: - -- Environment variables are correctly passed through to the output -- Environment variables with defaults are handled properly -- Volume mappings are correctly configured in the output - -### Test 2: Port Mappings - -Tests port mapping functionality for both Docker run commands and Docker Compose files. It verifies: - -- Basic port mappings are correctly translated -- Multiple port mappings are handled properly -- Database service port configurations are correctly set -- PORT environment variables are properly set - -### Test 3: Environment Variable Substitution - -Tests the functionality to substitute environment variables from a .env file. It verifies: - -- Environment variables can be substituted with values from a .env file -- Default values are used when variables are not defined -- Substitution works in both Docker run and Docker Compose scenarios - -### Test 4: Schema Validation - -Tests that the generated Render.com YAML output conforms to the official Render.com schema. It verifies: - -- Output is valid according to the Render.com schema -- Required fields are present and correctly formatted -- Service configurations are properly structured - -## Test Output Structure - -End-to-end tests generate organized output directories: - -```bash -test/e2e/output/ -├── test1/ # Environment variables and volume mapping test -│ ├── docker-compose/ # Docker Compose test outputs -│ │ ├── dop/ # DigitalOcean outputs -│ │ │ └── .do/ -│ │ │ └── deploy.template.yaml -│ │ └── rnd/ # Render outputs -│ │ └── render.yaml -│ └── docker-run/ # Docker run test outputs -│ ├── dop/ -│ │ └── .do/ -│ │ └── deploy.template.yaml -│ └── rnd/ -│ └── render.yaml -├── test2/ # Port mapping test -│ ├── docker-compose/ -│ │ ├── dop/ -│ │ │ └── .do/ -│ │ │ └── deploy.template.yaml -│ │ └── rnd/ -│ │ └── render.yaml -│ └── docker-run/ -│ ├── dop/ -│ │ └── .do/ -│ │ └── deploy.template.yaml -│ └── rnd/ -│ └── render.yaml -└── ... -``` - -## Adding Test Cases - -### For Docker Compose Tests - -Add your test files to `test/e2e/docker-compose-files/` with `.yml` or `.yaml` extension. Each file should represent a specific test scenario. - -### For Docker Run Commands - -Add your test commands to `test/e2e/docker-run-files/` with `.txt` extension. Each file should contain a single Docker run command. You can use line continuations with `\` for readability: - -```bash -docker run -d \ - --name nginx-proxy \ - -p 80:80 \ - -v /etc/nginx/conf.d:/etc/nginx/conf.d:ro \ - nginx:alpine -``` - -### Adding New End-to-End Tests - -To add a new end-to-end test: - -1. Create a new test file (e.g., `test5.ts`) in `test/e2e/` -2. Follow the pattern of existing test files: - - Define the test scenario - - Create test functions for Docker run and Docker Compose - - Use assertions to validate the output -3. Add your test to `test/e2e/index.ts` to ensure it gets executed - -### Adding Assertions - -For new validation requirements: - -1. Add assertion functions to the appropriate file in `test/e2e/assertions/` -2. Use these assertions in your test functions -3. For provider-specific assertions, create new files if needed - -## Unit Tests - -Unit tests validate individual components of the codebase: - -- **Config tests**: Verify configuration files and settings -- **Parser tests**: Check that parsers handle input correctly -- **Source tests**: Validate source handling (Docker run, Docker Compose) -- **Utility tests**: Ensure utility functions work as expected - -To add a new unit test: - -1. Create a new test file in the appropriate directory under `test/unit/` -2. Use the Vitest framework for testing (similar to Jest) -3. Follow the naming convention: `*.test.ts` - -## Local Testing with `npm link` - -Test locally using `npm link`. Development environment setup: - -```bash -some-root-dir/ -|-- docker-to-iac/ -|-- my-dev-env/ -| |-- index.js -| |-- docker-compose.yml -| |-- docker-run.txt -| |-- node_modules/ -| |-- package.json -``` - -Setup steps: - -1. In `docker-to-iac/`: `npm link` -2. In `my-dev-env`: `npm link @deploystack/docker-to-iac` - -### Setting up my-dev-env - -1. Initialize: `npm init` - -2. Create `index.js`: - -```javascript -import { translate } from '@deploystack/docker-to-iac'; -import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs'; -import { join, dirname } from 'path'; - -// Test Docker Compose -const dockerComposeContent = readFileSync('docker-compose.yml', 'utf8'); -const composeResult = translate(dockerComposeContent, { - source: 'compose', - target: 'RND', // Render.com output - templateFormat: 'yaml' -}); - -console.log('Docker Compose Translation - Files:', Object.keys(composeResult.files)); - -// Write output files preserving directory structure -Object.entries(composeResult.files).forEach(([path, fileData]) => { - const fullPath = join('output', 'compose', path); - const dir = dirname(fullPath); - - if (!existsSync(dir)) { - mkdirSync(dir, { recursive: true }); - } - - writeFileSync(fullPath, fileData.content); -}); - -// Test Docker Run -const dockerRunContent = readFileSync('docker-run.txt', 'utf8'); -const runResult = translate(dockerRunContent, { - source: 'run', - target: 'DOP', // DigitalOcean output - templateFormat: 'yaml' -}); - -console.log('Docker Run Translation - Files:', Object.keys(runResult.files)); - -// Write output files preserving directory structure -Object.entries(runResult.files).forEach(([path, fileData]) => { - const fullPath = join('output', 'run', path); - const dir = dirname(fullPath); - - if (!existsSync(dir)) { - mkdirSync(dir, { recursive: true }); - } - - writeFileSync(fullPath, fileData.content); -}); -``` - -3. Test changes: - - Make changes in `docker-to-iac/` - - Run `npm run build` in docker-to-iac - - Test in `my-dev-env/` with `node index.js` - - Check the output directory for generated files - -## Test Results - -The test suite shows detailed results for each test: - -- Unit tests show individual function validation results -- E2E tests provide a summary of passed and failed tests -- Test failures include specific error messages for debugging - -On failure: - -- Error details are logged -- Process exits with code 1 -- GitHub Actions fails PR check - -## Code Coverage - -To generate code coverage reports: - -```bash -npm run test:coverage -``` - -This will create coverage reports in the `coverage/` directory, including HTML reports you can view in a browser. - -## Troubleshooting Test Failures - -If tests fail: - -1. Check the test output for specific error messages -2. Review the actual and expected values in assertion failures -3. Check the generated files in `test/e2e/output/` to see what was produced -4. For schema validation failures, check the error details against the provider's schema documentation - -By following these steps, you can ensure your changes are fully tested and compatible with all supported output formats. From 9ed07db2b86c8c29b775be3992774cc8ad3cb99f Mon Sep 17 00:00:00 2001 From: Lasim Date: Fri, 20 Jun 2025 17:53:23 +0200 Subject: [PATCH 10/17] docs: add sidebar entries for improved navigation in docker-to-iac documentation --- docs/docker-to-iac/api.mdx | 1 + docs/docker-to-iac/environment-variable.mdx | 1 + docs/docker-to-iac/meta.json | 30 ++++++++++++++++++- .../multi-file-configuration.mdx | 1 + docs/docker-to-iac/parser/helm.mdx | 1 + docs/docker-to-iac/parser/render.com.mdx | 1 + docs/docker-to-iac/quickstart.mdx | 3 +- docs/docker-to-iac/service-connections.mdx | 1 + 8 files changed, 37 insertions(+), 2 deletions(-) diff --git a/docs/docker-to-iac/api.mdx b/docs/docker-to-iac/api.mdx index faa0160..dd242cc 100644 --- a/docs/docker-to-iac/api.mdx +++ b/docs/docker-to-iac/api.mdx @@ -1,6 +1,7 @@ --- title: docker-to-iac module API description: Here's everything you need to know about our docker-to-iac module - from listing available cloud providers to converting your Docker setup into deployable code. +sidebar: Module API --- # docker-to-iac module API list diff --git a/docs/docker-to-iac/environment-variable.mdx b/docs/docker-to-iac/environment-variable.mdx index f981306..10ccf59 100644 --- a/docs/docker-to-iac/environment-variable.mdx +++ b/docs/docker-to-iac/environment-variable.mdx @@ -1,6 +1,7 @@ --- title: Environment Variables in docker-to-iac description: Learn how to manage environment variables in docker-to-iac. Pass configuration values from .env files to your Infrastructure as Code templates and keep your sensitive data secure. +sidebar: Environment Variables --- # Environment Variables diff --git a/docs/docker-to-iac/meta.json b/docs/docker-to-iac/meta.json index 0e355f0..69fa5dd 100644 --- a/docs/docker-to-iac/meta.json +++ b/docs/docker-to-iac/meta.json @@ -2,5 +2,33 @@ "title": "docker-to-iac", "description": "docker-to-iac module", "icon": "Container", - "root": true + "root": true, + "pages": [ + "!index.mdx", + "quickstart.mdx", + "---General---", + "supported-docker-compose-variables.mdx", + "supported-registries.mdx", + "limitations.mdx", + "api.mdx", + "parser-explanation.mdx", + "environment-variable.mdx", + "environment-variable-generation.mdx", + "multi-services-support.mdx", + "multi-file-configuration.mdx", + "service-connections.mdx", + "---Available Parsers---", + "parser/digitalocean.mdx", + "parser/render.com.mdx", + "parser/helm.mdx", + "parser/aws-cloudformation.mdx", + "---Contributing---", + "before-you-start.mdx", + "project-structure.mdx", + "available-commands.mdx", + "example-of-a-new-parser.mdx", + "testing.mdx", + "publishing-to-npm.mdx", + "render-contributing-to-service-types.mdx" + ] } diff --git a/docs/docker-to-iac/multi-file-configuration.mdx b/docs/docker-to-iac/multi-file-configuration.mdx index e070976..2d1d6ab 100644 --- a/docs/docker-to-iac/multi-file-configuration.mdx +++ b/docs/docker-to-iac/multi-file-configuration.mdx @@ -1,6 +1,7 @@ --- title: Multi-File Configuration in docker-to-iac description: Learn how docker-to-iac supports complex Infrastructure as Code templates with multiple interconnected files, including Helm Charts and other multi-file IaC formats. +sidebar: Multi-File Configuration --- # Multi-File Configuration in docker-to-iac diff --git a/docs/docker-to-iac/parser/helm.mdx b/docs/docker-to-iac/parser/helm.mdx index 5c397d4..b61ff17 100644 --- a/docs/docker-to-iac/parser/helm.mdx +++ b/docs/docker-to-iac/parser/helm.mdx @@ -1,6 +1,7 @@ --- title: Helm Parser Documentation description: Translate Docker Compose files into Kubernetes Helm Charts with DeployStack docker-to-iac module +sidebar: Helm Parser --- # Helm - Parser Full Documentation diff --git a/docs/docker-to-iac/parser/render.com.mdx b/docs/docker-to-iac/parser/render.com.mdx index 771e914..ecd67b9 100644 --- a/docs/docker-to-iac/parser/render.com.mdx +++ b/docs/docker-to-iac/parser/render.com.mdx @@ -1,6 +1,7 @@ --- title: Render.com - Parser Full Documentation description: Translate docker docker-compose.yml file into Render.com Infrastructure as Code with DeployStack +sidebar: Render.com Parser --- # Render.com - Parser Full Documentation diff --git a/docs/docker-to-iac/quickstart.mdx b/docs/docker-to-iac/quickstart.mdx index a958678..602824c 100644 --- a/docs/docker-to-iac/quickstart.mdx +++ b/docs/docker-to-iac/quickstart.mdx @@ -1,9 +1,10 @@ --- title: Quickstart Guide description: Quickstart guide for using docker-to-iac to translate Docker run commands and Docker Compose files into infrastructure as code templates +icon: Album --- -# Quickstart Guide +# Quickstart Guide to docker-to-iac ## Installation diff --git a/docs/docker-to-iac/service-connections.mdx b/docs/docker-to-iac/service-connections.mdx index 9622e7e..2fa4b06 100644 --- a/docs/docker-to-iac/service-connections.mdx +++ b/docs/docker-to-iac/service-connections.mdx @@ -1,6 +1,7 @@ --- title: Service Connections in docker-to-iac description: Configure service-to-service communication in multi-container applications with docker-to-iac's service connections feature. Transform Docker Compose service references to cloud provider formats. +sidebar: Service Connections --- # Service Connections From c069547ffd90c00ec7c47b83dec2ee70737a758c Mon Sep 17 00:00:00 2001 From: Lasim Date: Sat, 21 Jun 2025 08:19:05 +0200 Subject: [PATCH 11/17] Add comprehensive documentation for DeployStack features and configurations - Introduced .deploystack directory reference for managing Infrastructure as Code templates. - Detailed Docker Compose requirements and supported properties. - Explained environment variable management in DeployStack. - Provided a step-by-step guide for getting started with DeployStack. - Documented GitHub application integration for automatic template updates. - Outlined the Infrastructure as Code lifecycle and update triggers. - Established a branch strategy for maintaining multiple application versions. - Implemented one-click deployment documentation for cloud providers. - Created a troubleshooting guide for common DeployStack issues. --- app/[[...slug]]/page.tsx | 14 ++- docs/deploystack/meta.json | 2 +- .../application-logo-configuration.mdx | 0 .../deploystack-config-file.mdx | 0 .../deploystack-configuration-directory.mdx | 0 .../docker-compose-requirements.mdx | 0 .../docker-environment-variables.mdx | 1 + .../getting-started.mdx | 2 + .../github-application.mdx | 0 .../iac-lifecycle.mdx | 0 docs/docker-deployment/index.mdx | 23 +++++ docs/docker-deployment/meta.json | 15 +++ .../multiple-branches.mdx | 0 .../one-click-deploy.mdx | 0 .../troubleshooting.mdx | 1 + docs/meta.json | 6 +- sidebar-links.legacy.json | 91 ------------------- 17 files changed, 61 insertions(+), 94 deletions(-) rename docs/{deploystack => docker-deployment}/application-logo-configuration.mdx (100%) rename docs/{deploystack => docker-deployment}/deploystack-config-file.mdx (100%) rename docs/{deploystack => docker-deployment}/deploystack-configuration-directory.mdx (100%) rename docs/{deploystack => docker-deployment}/docker-compose-requirements.mdx (100%) rename docs/{deploystack => docker-deployment}/docker-environment-variables.mdx (98%) rename docs/{deploystack => docker-deployment}/getting-started.mdx (99%) rename docs/{deploystack => docker-deployment}/github-application.mdx (100%) rename docs/{deploystack => docker-deployment}/iac-lifecycle.mdx (100%) create mode 100644 docs/docker-deployment/index.mdx create mode 100644 docs/docker-deployment/meta.json rename docs/{deploystack => docker-deployment}/multiple-branches.mdx (100%) rename docs/{deploystack => docker-deployment}/one-click-deploy.mdx (100%) rename docs/{deploystack => docker-deployment}/troubleshooting.mdx (99%) delete mode 100644 sidebar-links.legacy.json diff --git a/app/[[...slug]]/page.tsx b/app/[[...slug]]/page.tsx index 94cd965..ce9e44b 100644 --- a/app/[[...slug]]/page.tsx +++ b/app/[[...slug]]/page.tsx @@ -8,6 +8,7 @@ import { getFinalPageTitle } from '@/lib/h1-extractor'; import { readFile } from 'fs/promises'; import { getMDXComponents } from '@/mdx-components'; import { baseOptions } from '../layout.config'; +import { docs } from '@/.source/index'; export default async function Page({ params, @@ -45,7 +46,18 @@ export default async function Page({ } export async function generateStaticParams() { - return source.generateParams(); + const params = source.generateParams(); + + const result = [ + ...params, + ...docs.docs + .filter((page: any) => page._file.flattenedPath) + .map((page: any) => ({ + slug: page._file.flattenedPath.split('/'), + })), + ]; + + return result; } export async function generateMetadata({ diff --git a/docs/deploystack/meta.json b/docs/deploystack/meta.json index cbff948..dbe3c80 100644 --- a/docs/deploystack/meta.json +++ b/docs/deploystack/meta.json @@ -1,5 +1,5 @@ { - "title": "DeployStack", + "title": "Docker Deployment", "description": "Documentation for DeployStack", "icon": "DeployStackLogo", "root": true diff --git a/docs/deploystack/application-logo-configuration.mdx b/docs/docker-deployment/application-logo-configuration.mdx similarity index 100% rename from docs/deploystack/application-logo-configuration.mdx rename to docs/docker-deployment/application-logo-configuration.mdx diff --git a/docs/deploystack/deploystack-config-file.mdx b/docs/docker-deployment/deploystack-config-file.mdx similarity index 100% rename from docs/deploystack/deploystack-config-file.mdx rename to docs/docker-deployment/deploystack-config-file.mdx diff --git a/docs/deploystack/deploystack-configuration-directory.mdx b/docs/docker-deployment/deploystack-configuration-directory.mdx similarity index 100% rename from docs/deploystack/deploystack-configuration-directory.mdx rename to docs/docker-deployment/deploystack-configuration-directory.mdx diff --git a/docs/deploystack/docker-compose-requirements.mdx b/docs/docker-deployment/docker-compose-requirements.mdx similarity index 100% rename from docs/deploystack/docker-compose-requirements.mdx rename to docs/docker-deployment/docker-compose-requirements.mdx diff --git a/docs/deploystack/docker-environment-variables.mdx b/docs/docker-deployment/docker-environment-variables.mdx similarity index 98% rename from docs/deploystack/docker-environment-variables.mdx rename to docs/docker-deployment/docker-environment-variables.mdx index 672cfef..716b79b 100644 --- a/docs/deploystack/docker-environment-variables.mdx +++ b/docs/docker-deployment/docker-environment-variables.mdx @@ -1,6 +1,7 @@ --- title: Environment Variables in DeployStack description: Learn how to manage environment variables in DeployStack using the .deploystack/env file. Support for Docker Compose, Docker run commands, and default values. +sidebar: Environment Variables --- # Environment Variables in DeployStack diff --git a/docs/deploystack/getting-started.mdx b/docs/docker-deployment/getting-started.mdx similarity index 99% rename from docs/deploystack/getting-started.mdx rename to docs/docker-deployment/getting-started.mdx index c441f15..a9260dc 100644 --- a/docs/deploystack/getting-started.mdx +++ b/docs/docker-deployment/getting-started.mdx @@ -1,6 +1,8 @@ --- title: Getting Started with DeployStack description: Start deploying Docker applications across cloud providers with DeployStack. Step-by-step guide to generating infrastructure templates from Docker configurations. +sidebar: Getting Started +icon: Album --- # Getting Started with DeployStack diff --git a/docs/deploystack/github-application.mdx b/docs/docker-deployment/github-application.mdx similarity index 100% rename from docs/deploystack/github-application.mdx rename to docs/docker-deployment/github-application.mdx diff --git a/docs/deploystack/iac-lifecycle.mdx b/docs/docker-deployment/iac-lifecycle.mdx similarity index 100% rename from docs/deploystack/iac-lifecycle.mdx rename to docs/docker-deployment/iac-lifecycle.mdx diff --git a/docs/docker-deployment/index.mdx b/docs/docker-deployment/index.mdx new file mode 100644 index 0000000..2203faa --- /dev/null +++ b/docs/docker-deployment/index.mdx @@ -0,0 +1,23 @@ +--- +title: DeployStack Documentation +description: Official DeployStack documentation - Learn how to automate Docker Compose and run deployments across cloud providers. Clear guides and technical references for effective deployment automation. +menuTitle: DeployStack +--- + +# DeployStack - Open Source Cloud Deployment Guide + +DeployStack helps you deploy Docker Compose and Docker Run applications across different cloud providers by automatically generating Infrastructure as Code templates. Our documentation guides you through using DeployStack effectively. + +## Documentation Sections + +- [Getting Started](/deploystack/getting-started) - Quick introduction and first steps +- [Docker Compose Requirements](/deploystack/docker-compose-requirements) - Learn about supported configurations +- [One-Click Deploy](/deploystack/one-click-deploy) - Learn about deployment automation +- [Troubleshooting](/deploystack/troubleshooting) - Resolve common issues + +## Additional Resources + +- [Docker-to-IaC Module Documentation](/docker-to-iac/index) +- [Join our Discord](https://discord.gg/UjFWwByB) +- [Visit DeployStack](https://deploystack.io) + diff --git a/docs/docker-deployment/meta.json b/docs/docker-deployment/meta.json new file mode 100644 index 0000000..e905f80 --- /dev/null +++ b/docs/docker-deployment/meta.json @@ -0,0 +1,15 @@ +{ + "title": "Docker Deployment", + "description": "Docker Deployment", + "icon": "Container", + "root": true, + "pages": [ + "!index.mdx", + "getting-started.mdx", + "---General---", + "one-click-deploy.mdx", + "deploystack-configuration-directory.mdx", + "deploystack-config-file.mdx", + "..." + ] +} diff --git a/docs/deploystack/multiple-branches.mdx b/docs/docker-deployment/multiple-branches.mdx similarity index 100% rename from docs/deploystack/multiple-branches.mdx rename to docs/docker-deployment/multiple-branches.mdx diff --git a/docs/deploystack/one-click-deploy.mdx b/docs/docker-deployment/one-click-deploy.mdx similarity index 100% rename from docs/deploystack/one-click-deploy.mdx rename to docs/docker-deployment/one-click-deploy.mdx diff --git a/docs/deploystack/troubleshooting.mdx b/docs/docker-deployment/troubleshooting.mdx similarity index 99% rename from docs/deploystack/troubleshooting.mdx rename to docs/docker-deployment/troubleshooting.mdx index c125d48..88c0c22 100644 --- a/docs/deploystack/troubleshooting.mdx +++ b/docs/docker-deployment/troubleshooting.mdx @@ -1,6 +1,7 @@ --- title: Troubleshooting DeployStack Issues description: Technical solutions for common DeployStack deployment issues. Find answers to repository submission errors, license restrictions, and Docker Compose validation problems. +sidebar: Troubleshooting --- # Troubleshooting diff --git a/docs/meta.json b/docs/meta.json index d096ec2..eeb3e14 100644 --- a/docs/meta.json +++ b/docs/meta.json @@ -1,3 +1,7 @@ { - "pages": ["deploystack", "docker-to-iac"] + "pages": [ + "deploystack", + "docker-to-iac", + "docker-deployment" + ] } \ No newline at end of file diff --git a/sidebar-links.legacy.json b/sidebar-links.legacy.json deleted file mode 100644 index 47b8ff5..0000000 --- a/sidebar-links.legacy.json +++ /dev/null @@ -1,91 +0,0 @@ -[ - { - "text": "DeployStack", - "link": "/docs/deploystack", - "image": "https://deploystack.io/assets/images/deploystack-logo-transparent-16x16.webp", - "items": [ - { - "text": "Getting Started", - "link": "/docs/deploystack/getting-started.md" - }, - { - "text": "Configuration Directory", - "link": "/docs/deploystack/deploystack-configuration-directory.md" - }, - { - "text": "Configuration File", - "link": "/docs/deploystack/deploystack-config-file.md" - }, - { - "text": "Application Logo Configuration", - "link": "/docs/deploystack/application-logo-configuration.md" - }, - { - "text": "IaC Lifecycle", - "link": "/docs/deploystack/iac-lifecycle.md" - }, - { - "text": "GitHub Applicaton", - "link": "/docs/deploystack/github-application.md" - }, - { - "text": "One Click Deploy", - "link": "/docs/deploystack/one-click-deploy.md" - }, - { - "text": "Docker Compose Requirements", - "link": "/docs/deploystack/docker-compose-requirements.md" - }, - { - "text": "Docker Environment Variables", - "link": "/docs/deploystack/docker-environment-variables.md" - }, - { - "text": "Troubleshooting", - "link": "/docs/deploystack/troubleshooting.md" - } - ] - }, - { - "text": "Docker-To-IaC", - "link": "/docs/docker-to-iac", - "icon": "Container", - "items": [ - { - "text": "Usage & Concept", - "items": [ - { "text": "Quickstart", "link": "/docs/docker-to-iac/quickstart.md" }, - { "text": "API", "link": "/docs/docker-to-iac/api.md" }, - { "text": "Passing Environment Variable", "link": "/docs/docker-to-iac/environment-variable.md" }, - { "text": "Environment Variable Generation", "link": "/docs/docker-to-iac/environment-variable-generation.md" }, - { "text": "Parser Explanation", "link": "/docs/docker-to-iac/parser-explanation.md" }, - { "text": "Multi Services Support", "link": "/docs/docker-to-iac/multi-services-support.md" }, - { "text": "Supported Docker Compose Variables", "link": "/docs/docker-to-iac/supported-docker-compose-variables.md" }, - { "text": "Supported Registries", "link": "/docs/docker-to-iac/supported-registries.md" }, - { "text": "Limitations", "link": "/docs/docker-to-iac/limitations" } - ] - }, - { - "text": "Parsers", - "link": "/docs/docker-to-iac/parser.md", - "items": [ - { "text": "AWS CloudFormation", "link": "/docs/docker-to-iac/parser/aws-cloudformation.md" }, - { "text": "Render.com", "link": "/docs/docker-to-iac/parser/render.com.md" }, - { "text": "DigitalOcean", "link": "/docs/docker-to-iac/parser/digitalocean" } - ] - }, - { - "text": "Development", - "items": [ - { "text": "Before you Start", "link": "/docs/docker-to-iac/before-you-start.md" }, - { "text": "Available Commands", "link": "/docs/docker-to-iac/available-commands.md" }, - { "text": "Project Structure", "link": "/docs/docker-to-iac/project-structure.md" }, - { "text": "Render: Contributing to Service Types", "link": "/docs/docker-to-iac/render-contributing-to-service-types.md" }, - { "text": "Testing", "link": "/docs/docker-to-iac/testing.md" }, - { "text": "Example of a New Parser", "link": "/docs/docker-to-iac/example-of-a-new-parser.md" }, - { "text": "Publishing to npm", "link": "/docs/docker-to-iac/publishing-to-npm.md" } - ] - } - ] - } -] From 9e0a678626dd442f04c43466729dd5f77b26b466 Mon Sep 17 00:00:00 2001 From: Lasim Date: Sat, 21 Jun 2025 08:42:04 +0200 Subject: [PATCH 12/17] feat: implement HomeLayout for root page and update layout configuration --- app/[[...slug]]/page.tsx | 17 +++++++++++++++++ app/layout.config.tsx | 19 +++++++++++++++++++ public/favicon.ico | Bin 0 -> 4286 bytes 3 files changed, 36 insertions(+) create mode 100644 public/favicon.ico diff --git a/app/[[...slug]]/page.tsx b/app/[[...slug]]/page.tsx index ce9e44b..6c2e668 100644 --- a/app/[[...slug]]/page.tsx +++ b/app/[[...slug]]/page.tsx @@ -1,5 +1,6 @@ import type { Metadata } from 'next'; import { DocsLayout } from 'fumadocs-ui/layouts/docs'; +import { HomeLayout } from 'fumadocs-ui/layouts/home'; import { DocsPage, DocsBody } from 'fumadocs-ui/page'; import { notFound } from 'next/navigation'; import { source } from '@/lib/source'; @@ -24,6 +25,22 @@ export default async function Page({ const MDX = page.data.body; + // Determine if this is the root page (no sidebar needed) + const isRootPage = !slug || slug.length === 0; + + // Use HomeLayout for root page (no sidebar), DocsLayout for all other pages + if (isRootPage) { + return ( + +
+
+ +
+
+ + ); + } + return ( $b)s}=~z3`f%pAV@&aQB*)6FrtD{FqnWxYs7!yGWoeEVL{v`&b|n9ZXeuixMQ|9}78 z!!X^*->_i}{mPJ7&2$0vMHS>Skr;Oie2 zx}f2hEAH=i*4OTJKHiY+JVwN`ml0{NdzSNj4=@mXxtTkq|Fx5jTmMt&*jabZ6}6{a z@I&5&*6KqOTAKeuGZ8 z6KL_?+ujneTce-68<>&}%-Vrg`Ks#%`Lf}HK7~T)32F!I`lIDbi6`;@JM44^c6!3H zUSdRsG~h)xfQOKqCJ)u)YIMut8T`@-bWJu*p5uMN7(EEtaUS!O-B<0`STef#+_gv16zzHN&fvO zQsv(%U)R+ZnmI`;|GXKIYoLorwHRYk{3%bBT;9u`x7@Dg^c!3Uo7YJmV7nKwL2{Jx z(Rn4Dw*Jz%sorUp=0AbgDYQtB%n{zXsons?JJ24aHde`b0mC@s^Y_}qmp??z3h1L3 zTa58ZGJ(H~4FYYm+Z)1};TDT+o&;a|80*~sEYN7qNUzc7R=2#7P0}Nl7O4u&lKc;Z z_XL}s_6s%}bP;I-brDM+ApTPr;u1}UganrIf&Y0N#J)p@>sYKOeX&+Taxm_FD=*EJ zHTO3>&W?T}Rhf+*q~_d}R$Xj)9~JQ%YEC&kEhNzuzbm#l*m^Hv@gQS@q8cd)K*}7LQshOZ z)G%*-YS`co-ro_cy^bT31IdN?@R3_!Dy;a79sXxN4WnZwYjI9?!(wz-0p6w1dljS3 z>oo3qU&LL%Dx704B~ssPxe(kW^&`w_ELqaGeL>9E_#_5c5d|!h!;~Iuz$$-WOCYeJ zFRtu4j)7-@=+gFI_`gW@bkw3i4I)FdrW>+LpK2rrPuIH_sH@$-ZmskzQQzXOQT*Lq z@#)>Zm)k#{JPbpr4Z}mSZM1zFTW}*MHoGJu;Rby1WE_;^U zyXt!zh2GcBQ+;&N_dJUpbc@)O9<{jbOe`7G;ad!K{GsZ%DQ!{_#)|lC=`ZU)(XVx6 zQh?f$6rx39Nb^6b4DC&^)-HLT54-Gh6UDOIILuX+?Ph-%MtSU4QdraAxHxS|>?amP z5&UTz+h>dK1^g1?e~HEHa~8tYi?(nkS< zo{1l}j!X0SK1_C+2+zjeMdiBmKI3&J$U#bkse zkx`j8uifh}eX-yy%3MVIn`R4H^%cJ2{VDVjWH0WgHQb-JuLQ0E7|j zprb%QfjOV%fXcoMThvQ)Ek4IZs=4^+wrlg}lbTE>b2F(;7oDu*lae5O(?mXcM)T+s zwyk}2=*|xPbS1&gC)mXQASGCl?^W0$pICF^JuXhCApX}Uq>@;W+Kx!o-JShe+nk6r z-N1+p-9Y&|L-e$b#(OjO05kRjA=#$7;M|UQQJ&(`UK8)X^|Z#q+9R`*n%*Y+lWosz|?K+9ih8SUj*miEdhh{7fb5)x8l8w&wjSWq-aM+ zF4Y&zPS@)qGYBr3Gt<|%w~<+MG;~Y*C{c$~mUR}3_y6|<@x|Vb*{S-$;k<#Jxz^+* z-;6<`eg(y~%@vXMN1j5x+vb(MUOH>UIc86P)ibm=feI&}@GV$ahn4Mow_JVqe}DX_ z*Z2XI-Gch=V@~$mua3yz`i$eawgDXXW*^SS-1`FiChx%ZWyvmd;QCf@T*f1gTl+VT o^Zw}qx33$wzrRDqzAL?ZR=Rffeblf20IHMfrWh1Uz$DoJ1E*GWbN~PV literal 0 HcmV?d00001 From ef2958eae8492cd3661efe02ae193d65d6f7e2b6 Mon Sep 17 00:00:00 2001 From: Lasim Date: Sat, 21 Jun 2025 08:48:03 +0200 Subject: [PATCH 13/17] feat: update Login link to use custom component with styling --- app/layout.config.tsx | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/app/layout.config.tsx b/app/layout.config.tsx index 915b765..a17e95e 100644 --- a/app/layout.config.tsx +++ b/app/layout.config.tsx @@ -20,9 +20,18 @@ export const baseOptions: BaseLayoutProps = { external: true, }, { - text: 'Login', - url: 'https://cloud.deploystack.io/login', - external: true, + type: 'custom', + secondary: true, + children: ( + + Login + + ), }, ], From 33cd63b2497b9f5f680338ba8b20f3fb2395b5a6 Mon Sep 17 00:00:00 2001 From: Lasim Date: Sat, 21 Jun 2025 21:20:20 +0200 Subject: [PATCH 14/17] Add comprehensive documentation for DeployStack development, global settings, user roles, permissions, and security practices - Created a detailed Development Guide covering frontend and backend setup, project structure, and key technologies. - Introduced Global Settings documentation for managing application configurations, including email and authentication settings. - Added User Roles and Permissions guide to explain role-based access control and team management. - Developed Security and Privacy documentation outlining account security measures, data protection, and best practices for users. --- .gitignore | 2 + app/layout.config.tsx | 2 +- docs/deploystack/development/backend/api.mdx | 373 +++++ .../development/backend/database.mdx | 230 +++ .../development/backend/global-settings.mdx | 1022 +++++++++++++ .../deploystack/development/backend/index.mdx | 143 ++ docs/deploystack/development/backend/mail.mdx | 645 ++++++++ .../deploystack/development/backend/meta.json | 4 + .../development/backend/plugins.mdx | 602 ++++++++ .../deploystack/development/backend/roles.mdx | 693 +++++++++ .../development/backend/security.mdx | 97 ++ docs/deploystack/development/backend/test.mdx | 150 ++ .../development/frontend/index.mdx | 388 +++++ .../frontend/internationalization.mdx | 882 +++++++++++ .../development/frontend/meta.json | 4 + .../development/frontend/plugins.mdx | 1299 +++++++++++++++++ .../frontend/router-optimization.mdx | 1022 +++++++++++++ docs/deploystack/development/index.mdx | 138 ++ docs/deploystack/global-settings.mdx | 135 ++ docs/deploystack/index.mdx | 43 +- docs/deploystack/meta.json | 5 +- docs/deploystack/roles.mdx | 191 +++ docs/deploystack/security.mdx | 187 +++ docs/index.mdx | 86 +- 24 files changed, 8295 insertions(+), 48 deletions(-) create mode 100644 docs/deploystack/development/backend/api.mdx create mode 100644 docs/deploystack/development/backend/database.mdx create mode 100644 docs/deploystack/development/backend/global-settings.mdx create mode 100644 docs/deploystack/development/backend/index.mdx create mode 100644 docs/deploystack/development/backend/mail.mdx create mode 100644 docs/deploystack/development/backend/meta.json create mode 100644 docs/deploystack/development/backend/plugins.mdx create mode 100644 docs/deploystack/development/backend/roles.mdx create mode 100644 docs/deploystack/development/backend/security.mdx create mode 100644 docs/deploystack/development/backend/test.mdx create mode 100644 docs/deploystack/development/frontend/index.mdx create mode 100644 docs/deploystack/development/frontend/internationalization.mdx create mode 100644 docs/deploystack/development/frontend/meta.json create mode 100644 docs/deploystack/development/frontend/plugins.mdx create mode 100644 docs/deploystack/development/frontend/router-optimization.mdx create mode 100644 docs/deploystack/development/index.mdx create mode 100644 docs/deploystack/global-settings.mdx create mode 100644 docs/deploystack/roles.mdx create mode 100644 docs/deploystack/security.mdx diff --git a/.gitignore b/.gitignore index c870832..1f65420 100644 --- a/.gitignore +++ b/.gitignore @@ -71,5 +71,7 @@ coverage/ .jest/ ._*.mdx +._*.md +._*.json ._*.ts out/ diff --git a/app/layout.config.tsx b/app/layout.config.tsx index a17e95e..0a0f73c 100644 --- a/app/layout.config.tsx +++ b/app/layout.config.tsx @@ -27,7 +27,7 @@ export const baseOptions: BaseLayoutProps = { href="https://cloud.deploystack.io/login" target="_blank" rel="noopener noreferrer" - className="text-slate-100 bg-slate-800 border border-slate-700 focus:outline-none hover:bg-slate-900 hover:text-slate-50 focus:ring-4 focus:ring-gray-100 font-medium rounded-full text-sm px-5 py-2.5 me-2 mb-2 dark:bg-gray-800 dark:text-white dark:border-gray-600 dark:hover:bg-gray-700 dark:hover:border-gray-600 dark:focus:ring-gray-700 transition-colors" + className="text-slate-100 bg-slate-800 border border-slate-700 ml-1.5 focus:outline-none hover:bg-slate-900 hover:text-slate-50 focus:ring-4 focus:ring-gray-100 font-medium rounded-full text-sm px-5 py-2 me-2 dark:bg-gray-800 dark:text-white dark:border-gray-600 dark:hover:bg-gray-700 dark:hover:border-gray-600 dark:focus:ring-gray-700 transition-colors" > Login diff --git a/docs/deploystack/development/backend/api.mdx b/docs/deploystack/development/backend/api.mdx new file mode 100644 index 0000000..b26b114 --- /dev/null +++ b/docs/deploystack/development/backend/api.mdx @@ -0,0 +1,373 @@ +--- +title: API Documentation Generation +description: Complete guide to generating OpenAPI specifications, Swagger documentation, and API testing tools for DeployStack Backend development. +--- + +# API Documentation Generation + +This document explains how to generate and use the OpenAPI specification for the DeployStack Backend API. + +## Overview + +The DeployStack Backend uses Fastify with Swagger plugins to automatically generate OpenAPI 3.0 specifications. Route schemas are defined using [Zod](https://zod.dev/) for type safety and expressiveness, and then converted to JSON Schema using the [zod-to-json-schema](https://www.npmjs.com/package/zod-to-json-schema) library. This provides: + +- **Interactive Documentation**: Swagger UI interface for testing APIs +- **Postman Integration**: JSON/YAML specs that can be imported into Postman +- **Automated Generation**: Specifications are generated from actual route code + +## Available Commands + +### 1. Generate Complete API Specification + +```bash +npm run api:spec +``` + +This command: + +- Starts a temporary server +- Generates both JSON and YAML specifications +- Saves files to `api-spec.json` and `api-spec.yaml` +- Provides URLs for interactive documentation +- Automatically shuts down the server + +**Output:** + +- `api-spec.json` - OpenAPI JSON specification (for Postman import) +- `api-spec.yaml` - OpenAPI YAML specification + +### 2. Generate JSON Specification (requires running server) + +```bash +npm run api:spec:json +``` + +Requires the development server to be running (`npm run dev`). + +### 3. Generate YAML Specification (requires running server) + +```bash +npm run api:spec:yaml +``` + +Requires the development server to be running (`npm run dev`). + +## Usage Examples + +### Complete Generation (Recommended) + +```bash +cd services/backend +npm run api:spec +``` + +### Manual Generation with Running Server + +```bash +# Terminal 1: Start the server +cd services/backend +npm run dev + +# Terminal 2: Generate specifications +npm run api:spec:json +npm run api:spec:yaml +``` + +## Accessing Documentation + +When the server is running (`npm run dev`), you can access: + +- **Interactive Docs**: http://localhost:3000/documentation +- **JSON Spec**: http://localhost:3000/documentation/json +- **YAML Spec**: http://localhost:3000/documentation/yaml + +## Importing into Postman + +1. Run `npm run api:spec` to generate the specification +2. Open Postman +3. Click "Import" +4. Select the generated `api-spec.json` file +5. All API endpoints will be imported with proper documentation + +## Adding Documentation to Routes + +To add OpenAPI documentation to your routes, define your request body and response schemas using Zod. Then, use the `zodToJsonSchema` utility to convert these Zod schemas into the JSON Schema format expected by Fastify. + +Make sure you have `zod` and `zod-to-json-schema` installed in your backend service. + +### Recommended Approach: Automatic Validation with Zod + +The power of Zod lies in providing **automatic validation** through Fastify's schema system. This approach eliminates manual validation and leverages Zod's full validation capabilities. + +```typescript +import { z } from 'zod'; +import { zodToJsonSchema } from 'zod-to-json-schema'; + +// 1. Define your Zod schemas for request body, responses, etc. +const myRequestBodySchema = z.object({ + name: z.string().min(3).describe("The name of the item (min 3 chars)"), + count: z.number().positive().describe("How many items (must be positive)"), + type: z.enum(['mysql', 'sqlite']).describe("Database engine type") +}); + +const mySuccessResponseSchema = z.object({ + success: z.boolean().describe("Indicates if the operation was successful"), + itemId: z.string().uuid().describe("The UUID of the created/affected item"), + message: z.string().optional().describe("Optional success message") +}); + +const myErrorResponseSchema = z.object({ + success: z.boolean().default(false).describe("Indicates failure"), + error: z.string().describe("Error message detailing what went wrong") +}); + +// 2. Construct the Fastify route schema using zodToJsonSchema +const routeSchema = { + tags: ['Category'], // Your API category + summary: 'Brief description of your endpoint', + description: 'Detailed description of what this endpoint does, its parameters, and expected outcomes.', + security: [{ cookieAuth: [] }], // Include if authentication is required + body: zodToJsonSchema(myRequestBodySchema, { + $refStrategy: 'none', // Keeps definitions inline, often simpler for Fastify + target: 'openApi3' // Ensures compatibility with OpenAPI 3.0 + }), + response: { + 200: zodToJsonSchema(mySuccessResponseSchema.describe("Successful operation"), { + $refStrategy: 'none', + target: 'openApi3' + }), + 400: zodToJsonSchema(myErrorResponseSchema.describe("Bad Request - Invalid input"), { + $refStrategy: 'none', + target: 'openApi3' + }), + // Define other responses (e.g., 401, 403, 404, 500) similarly + } +}; + +// 3. Use the schema in your Fastify route definition with proper TypeScript typing +interface RequestBody { + name: string; + count: number; + type: 'mysql' | 'sqlite'; +} + +fastify.post<{ Body: RequestBody }>( + '/your-route', + { schema: routeSchema }, + async (request, reply) => { + // ✅ Fastify has already validated request.body using our Zod schema + // ✅ If we reach here, request.body is guaranteed to be valid + // ✅ No manual validation needed! + + const { name, count, type } = request.body; // Fully typed and validated + + // Your route handler logic here + return reply.status(200).send({ + success: true, + itemId: 'some-uuid-v4-here', + message: `Item ${name} processed successfully with ${count} items using ${type}.` + }); + } +); +``` + +### Key Benefits of This Approach + +1. **Single Source of Truth**: Zod schemas define both validation AND documentation +2. **Automatic Validation**: Fastify automatically validates requests before your handler runs +3. **No Manual Validation**: Remove all manual `zod.parse()` calls and field checks +4. **Better Error Messages**: Fastify provides detailed validation errors automatically +5. **Type Safety**: Handlers receive properly typed, validated data +6. **Cleaner Code**: No redundant validation logic in handlers + +### What NOT to Do (Anti-patterns) + +❌ **Don't do manual validation in handlers:** + +```typescript +// BAD: Manual validation (redundant) +const parsedBody = myRequestBodySchema.safeParse(request.body); +if (!parsedBody.success) { + return reply.status(400).send({ error: 'Invalid request body' }); +} + +// BAD: Manual field checks (redundant) +if (!request.body.name || !request.body.count) { + return reply.status(400).send({ error: 'Required fields missing' }); +} + +// BAD: Manual enum validation (redundant) +if (request.body.type !== 'mysql' && request.body.type !== 'sqlite') { + return reply.status(400).send({ error: 'Invalid database type' }); +} +``` + +✅ **Do trust Fastify's automatic validation:** + +```typescript +// GOOD: Trust the validation - if handler runs, data is valid +const { name, count, type } = request.body; // Already validated by Fastify +``` + +### Validation Flow + +The validation chain works as follows: + +#### Zod Schema → JSON Schema → Fastify Validation → Handler + +1. **Zod Schema**: Define validation rules using Zod +2. **JSON Schema**: Convert to OpenAPI format using `zodToJsonSchema()` +3. **Fastify Validation**: Fastify automatically validates incoming requests +4. **Handler**: Receives validated, typed data + +If validation fails, Fastify automatically returns a 400 error **before** your handler runs. + +### Real-World Examples + +See these files for complete examples of proper Zod validation: + +- `src/routes/db/setup.ts` - Database setup with enum validation +- `src/routes/db/status.ts` - Simple GET endpoint with response schemas +- `src/routes/auth/loginEmail.ts` - Login with required string fields +- `src/routes/auth/registerEmail.ts` - Registration with complex validation rules + +**Note**: Older examples in this document (like the "Logout Route Documentation" below) might still show manually crafted JSON schemas. The recommended approach is now to use Zod with automatic Fastify validation as shown above. + +## Example: Logout Route Documentation + +The logout route (`/api/auth/logout`) demonstrates proper documentation: + +```typescript +const logoutSchema = { + tags: ['Authentication'], + summary: 'User logout', + description: 'Invalidates the current user session and clears authentication cookies', + security: [{ cookieAuth: [] }], + response: { + 200: { + type: 'object', + properties: { + success: { + type: 'boolean', + description: 'Indicates if the logout operation was successful' + }, + message: { + type: 'string', + description: 'Human-readable message about the logout result' + } + }, + required: ['success', 'message'], + examples: [ + { + success: true, + message: 'Logged out successfully.' + } + ] + } + } +}; +``` + +## Configuration + +The Swagger configuration is in `src/server.ts`: + +```typescript +await server.register(fastifySwagger, { + openapi: { + openapi: '3.0.0', + info: { + title: 'DeployStack Backend API', + description: 'API documentation for DeployStack Backend', + version: '0.20.5' + }, + servers: [ + { + url: 'http://localhost:3000', + description: 'Development server' + } + ], + components: { + securitySchemes: { + cookieAuth: { + type: 'apiKey', + in: 'cookie', + name: 'auth_session' + } + } + } + } +}); +``` + +## Troubleshooting + +### "Route already declared" Error + +This happens when trying to manually add routes that Swagger UI already provides. The `/documentation/json` and `/documentation/yaml` endpoints are automatically created. + +### "Failed to fetch API spec" Error + +Ensure the server is fully started before trying to fetch the specification. The generation script includes a 2-second delay to allow for complete initialization. + +### Missing Route Documentation + +Routes without schema definitions will appear in the specification but with minimal documentation. Add schema objects to routes for complete documentation. + +## Next Steps + +To extend API documentation: + +1. Add schema definitions to more routes +2. Define reusable components in the OpenAPI configuration +3. Add request body schemas for POST/PUT endpoints +4. Include error response schemas (400, 401, 500, etc.) +5. Add parameter validation schemas + +## Plugin API Routes + +### Plugin Route Structure + +All plugin routes are automatically namespaced under `/api/plugin//` for security and isolation: + +- **Core Routes**: `/api/auth/*`, `/api/users/*`, `/api/settings/*` (protected from plugins) +- **Plugin Routes**: `/api/plugin//*` (isolated per plugin) + +### Example Plugin Routes + +For a plugin with ID `example-plugin`: + +```bash +GET /api/plugin/example-plugin/examples +GET /api/plugin/example-plugin/examples/:id +POST /api/plugin/example-plugin/examples +PUT /api/plugin/example-plugin/examples/:id +DELETE /api/plugin/example-plugin/examples/:id +``` + +### Security Benefits + +1. **Route Isolation**: Plugins cannot interfere with core routes or each other +2. **Predictable Structure**: All plugin APIs follow the same pattern +3. **Easy Identification**: Plugin ownership is clear from the URL +4. **Automatic Namespacing**: No manual prefix management required + +### Plugin Route Registration + +Plugins register routes using the `PluginRouteManager`: + +```typescript +// In plugin's routes.ts file +export async function registerRoutes(routeManager: PluginRouteManager, db: AnyDatabase | null) { + // This becomes /api/plugin/my-plugin/data + routeManager.get('/data', async () => { + return { message: 'Hello from plugin!' }; + }); +} +``` + +## Files Generated + +- `api-spec.json` - Complete OpenAPI 3.0 specification in JSON format +- `api-spec.yaml` - Complete OpenAPI 3.0 specification in YAML format +- Interactive documentation available at `/documentation` when server is running diff --git a/docs/deploystack/development/backend/database.mdx b/docs/deploystack/development/backend/database.mdx new file mode 100644 index 0000000..a063206 --- /dev/null +++ b/docs/deploystack/development/backend/database.mdx @@ -0,0 +1,230 @@ +--- +title: Database Management +description: SQLite and PostgreSQL database setup, schema management, migrations, and plugin database extensions for DeployStack Backend development. +--- + +# Database Management + +## Overview + +DeployStack uses SQLite with Drizzle ORM for database operations. This combination provides excellent performance, type safety, and a modern, developer-friendly experience without the need for external database dependencies. + +## Database Setup and Configuration + +The backend server provides API endpoints for managing the initial database setup and checking its status. + +### Database Status + +You can check the current status of the database (whether it's configured and initialized) using the following endpoint: + +- **Endpoint:** `GET /api/db/status` +- **Method:** `GET` +- **Response:** A JSON object indicating the database `configured` status (boolean), `initialized` status (boolean), and current `dialect` (e.g., "sqlite" or "postgres", or null if not configured). + +### Initial Database Setup + +To perform the initial setup of the database, use the following endpoint: + +- **Endpoint:** `POST /api/db/setup` +- **Method:** `POST` +- **Request Body:** A JSON object specifying the database type and configuration. + +**For SQLite:** +The server will automatically manage the database file location. The request body should be: + +```json +{ + "type": "sqlite" +} +``` + +The SQLite database file will be created and stored at: `services/backend/persistent_data/database/deploystack.db`. + +**Important:** All database files must be stored within the `persistent_data` directory to ensure proper data persistence and backup capabilities. + +**For PostgreSQL:** +The request body should be: + +```json +{ + "type": "postgres", + "connectionString": "postgresql://username:password@host:port/mydatabase" +} +``` + +Replace the `connectionString` with your actual PostgreSQL connection URI. + +**Note:** The database setup is now complete in a single API call. After successful setup, all database-dependent services (global settings, plugins, etc.) are automatically initialized and ready to use immediately. No server restart is required. + +#### API Response + +The setup endpoint returns a JSON response indicating the success status and whether a restart is required: + +**Successful Setup (No Restart Required):** + +```json +{ + "message": "Database setup successful. All services have been initialized and are ready to use.", + "restart_required": false +} +``` + +**Successful Setup (Restart Required - Fallback):** + +```json +{ + "message": "Database setup successful, but some services may require a server restart to function properly.", + "restart_required": true +} +``` + +In most cases, the setup will complete successfully without requiring a restart. The `restart_required: true` response is a fallback for edge cases where the automatic re-initialization fails. + +### Database Configuration File + +The choice of database (SQLite or PostgreSQL) and its specific configuration (like the connection string for PostgreSQL) is stored in a JSON file located at: + +- `services/backend/persistent_data/db.selection.json` + +This file is automatically managed by the setup API. You typically do not need to edit it manually. + +## Key Components + +- **SQLite**: Embedded SQL database engine +- **Drizzle ORM**: Type-safe ORM for TypeScript +- **Drizzle Kit**: Schema migration tool for Drizzle ORM + +## Database Structure + +The database schema is defined in `src/db/schema.ts`. It contains: + +1. Base schema tables (core application) +2. Plugin tables (dynamically loaded) + +## Making Schema Changes + +Follow these steps to add or modify database tables: + +1. **Modify Schema Definition** + + Edit `src/db/schema.ts` to add or modify tables: + + ```typescript + // Example: Adding a new projects table + export const projects = sqliteTable('projects', { + id: text('id').primaryKey(), + name: text('name').notNull(), + description: text('description'), + userId: text('user_id').references(() => users.id), + createdAt: integer('created_at', { mode: 'timestamp' }).notNull().default(sql`(strftime('%s', 'now'))`), + updatedAt: integer('updated_at', { mode: 'timestamp' }).notNull().default(sql`(strftime('%s', 'now'))`), + }); + + // Don't forget to add it to baseSchema + export const baseSchema = { + users, + projects, // Add your new table here + }; + ``` + +2. **Generate Migration** + + Run the migration generation command: + + ```bash + npm run db:generate + ``` + + This will create SQL migration files in `drizzle/migrations/` based on your schema changes. + +3. **Review Migrations** + + Examine the generated SQL files in `drizzle/migrations/` to ensure they match your intended changes. + +4. **Apply Migrations** + + Either: + - Restart the application (migrations are applied on startup) + - Run migrations directly: + + ```bash + npm run db:up + ``` + +5. **Use the New Schema** + + Update your application code to use the new tables: + + ```typescript + // Example: Using the new table in a route + app.get('/api/projects', async (request, reply) => { + const projects = await request.db.select().from(schema.projects).all(); + return projects; + }); + ``` + +## Plugin Database Extensions + +Plugins can add their own tables through the `databaseExtension` property: + +1. Define tables in the plugin's `schema.ts` file +2. Include tables in the plugin's `databaseExtension.tables` array +3. Implement `onDatabaseInit()` for seeding or initialization + +Tables defined by plugins are automatically created when the plugin is loaded and initialized. + +## Migration Management + +- Migrations are tracked in a `__drizzle_migrations` table +- Only new migrations are applied when the server starts +- Migrations are applied in a transaction to ensure consistency + +## Development Workflow + +1. Make schema changes in `src/db/schema.ts` +2. Generate migrations with `npm run db:generate` +3. Restart the server to apply migrations +4. Update application code to use the modified schema + +## Best Practices + +- Use meaningful column names and consistent naming conventions +- Add appropriate indexes for columns that will be frequently queried +- Include proper foreign key constraints for relational data +- Add explicit types for all columns +- Always use migrations for schema changes in development and production +- **Important**: When adding foreign key relationships, update the dialect-specific schema files (e.g., `src/db/schema.sqlite.ts`) rather than the central `schema.ts` file, as Drizzle Kit uses these files for migration generation +- Never manually create migration files - always use `npm run db:generate` to ensure proper migration structure + +## Inspecting the Database + +You can inspect the SQLite database directly using various tools: + +- **SQLite CLI**: + + ```bash + sqlite3 services/backend/persistent_data/database/deploystack.db + ``` + + (Assuming the command is run from the project root directory) + +- **Visual Tools**: [DB Browser for SQLite](https://sqlitebrowser.org/) or VSCode extensions like SQLite Viewer + +## Troubleshooting + +### Database Setup Issues + +- **Setup fails with re-initialization error**: If the setup endpoint returns `restart_required: true`, you can manually restart the server to complete the setup process +- **Database already configured**: If you get a 409 error, the database has already been set up. Use the status endpoint to check the current configuration +- **Services not working after setup**: Check the server logs for any initialization errors. In rare cases, a manual restart may be needed + +### Migration Issues + +- If you get a "table already exists" error, check if you've already applied the migration +- For complex schema changes, you may need to create multiple migrations +- To reset the database, delete the `services/backend/persistent_data/database/deploystack.db` file and restart the server + +### Plugin Issues + +- **Plugins not working after setup**: Plugins with database extensions should automatically receive database access after setup. Check server logs for plugin re-initialization messages +- **Plugin database tables missing**: Ensure plugins are properly loaded before database setup, or restart the server if tables are missing diff --git a/docs/deploystack/development/backend/global-settings.mdx b/docs/deploystack/development/backend/global-settings.mdx new file mode 100644 index 0000000..550c0ef --- /dev/null +++ b/docs/deploystack/development/backend/global-settings.mdx @@ -0,0 +1,1022 @@ +--- +title: Global Settings Management +description: Comprehensive key-value store system with group organization, encryption support, and auto-initialization for DeployStack Backend configuration management. +--- + +# Global Settings Management + +This document describes the global key-value store system with group-based organization for managing application-wide configuration and credentials in DeployStack. + +## Overview + +The global settings system provides secure storage for application-wide configuration values organized into logical groups for better management and frontend display: + +- **SMTP Mail Settings**: Host, port, username, password for email functionality +- **GitHub OAuth Configuration**: GitHub OAuth client ID and secret for authentication +- **API Keys**: External service credentials (OpenAI, AWS, etc.) +- **System Configuration**: Application-wide settings and feature flags +- **Integration Credentials**: Third-party service authentication tokens +- **Environment Variables**: Dynamic configuration that can be changed without code deployment + +### Group-Based Organization + +The system now uses **groups** to organize settings into logical categories that can be displayed as tabs in the frontend: + +- **Group ID**: Technical identifier used for API queries (e.g., `smtp`) +- **Group Name**: Human-readable display name (e.g., `SMTP Mail Settings`) +- **Group Metadata**: Description, icon, and sort order for frontend display + +### Auto-Initialization System + +The system includes an **auto-initialization feature** that automatically creates missing groups and global settings when the server starts. Settings are defined in modular files within the `src/global-settings/` directory, and the system will: + +- Scan for setting definition files on startup +- Create missing groups with metadata +- Check which settings exist in the database +- Create missing settings with default values (non-destructive) +- Link settings to their appropriate groups +- Preserve existing settings and their values +- Log initialization results for transparency + +## Key Features + +- **Group-Based Organization**: Settings organized into logical groups for frontend tabs +- **Hierarchical Keys**: Dot notation organization (e.g., `smtp.host`, `api.openai.key`) +- **Encryption Support**: Automatic encryption for sensitive values using AES-256-GCM +- **Group Metadata**: Display names, descriptions, icons, and sort order for groups +- **Admin-Only Access**: Only `global_admin` users can manage settings +- **Type Safety**: Zod schema validation for all inputs +- **Audit Trail**: Track setting changes with timestamps +- **Search Functionality**: Find settings by key patterns +- **Bulk Operations**: Create/update multiple settings at once +- **Health Monitoring**: Built-in encryption system health checks + +## Security + +### Encryption + +Sensitive values are encrypted using industry-standard AES-256-GCM encryption: + +- **Algorithm**: AES-256-GCM (Galois/Counter Mode) +- **Key Derivation**: Scrypt with fixed salt from `DEPLOYSTACK_ENCRYPTION_SECRET` environment variable +- **Authenticated Encryption**: Prevents tampering with encrypted data +- **Unique IVs**: Each encryption operation uses a unique initialization vector +- **Additional Authenticated Data**: Extra security layer to prevent manipulation + +### Access Control + +- **Role-Based Access**: Only users with `global_admin` role can access settings +- **Permission-Based**: Granular permissions for view, edit, and delete operations +- **Session Validation**: All requests require valid authentication + +### Environment Variables + +The system requires the `DEPLOYSTACK_ENCRYPTION_SECRET` environment variable: + +```bash +DEPLOYSTACK_ENCRYPTION_SECRET=your-very-secure-32-character-secret-key-here +``` + +**Important**: Use a strong, unique secret in production. This key is used to derive the encryption key for all sensitive settings. + +## Database Schema + +```sql +-- Groups table for organizing settings +CREATE TABLE globalSettingGroups ( + id TEXT PRIMARY KEY, -- Group identifier (e.g., 'smtp') + name TEXT NOT NULL, -- Display name (e.g., 'SMTP Mail Settings') + description TEXT, -- Group description + icon TEXT, -- Optional icon (lucide) for frontend + sort_order INTEGER DEFAULT 0 NOT NULL, -- Display order for tabs + created_at INTEGER NOT NULL, -- Creation timestamp + updated_at INTEGER NOT NULL -- Last update timestamp +); + +-- Settings table with group reference +CREATE TABLE globalSettings ( + key TEXT PRIMARY KEY, -- Setting identifier (e.g., 'smtp.host') + value TEXT NOT NULL, -- Setting value (encrypted if sensitive) + description TEXT, -- Human-readable description + is_encrypted BOOLEAN NOT NULL DEFAULT FALSE, -- Whether value is encrypted + group_id TEXT REFERENCES globalSettingGroups(id), -- Group reference + created_at INTEGER NOT NULL, -- Creation timestamp + updated_at INTEGER NOT NULL -- Last update timestamp +); +``` + +## API Endpoints + +### Authentication + +All endpoints require authentication and appropriate permissions: + +- **View Settings**: Requires `settings.view` permission +- **Create/Update Settings**: Requires `settings.edit` permission +- **Delete Settings**: Requires `settings.delete` permission + +### Group Management + +#### Get All Groups with Settings + +```http +GET /api/settings/groups +Authorization: Bearer +``` + +**Response:** + +```json +{ + "success": true, + "data": [ + { + "id": "smtp", + "name": "SMTP Mail Settings", + "description": "Email server configuration for sending notifications", + "icon": "mail", + "sort_order": 1, + "settings": [ + { + "key": "smtp.host", + "value": "smtp.gmail.com", + "description": "SMTP server hostname", + "is_encrypted": false, + "created_at": "2025-01-06T20:00:00.000Z", + "updated_at": "2025-01-06T20:00:00.000Z" + } + ], + "created_at": "2025-01-06T20:00:00.000Z", + "updated_at": "2025-01-06T20:00:00.000Z" + } + ] +} +``` + +#### Get Specific Group + +```http +GET /api/settings/groups/:groupId +Authorization: Bearer +``` + +#### Create Group + +```http +POST /api/settings/groups +Authorization: Bearer +Content-Type: application/json + +{ + "id": "api-keys", + "name": "API Keys", + "description": "External service API keys and credentials", + "icon": "key", + "sort_order": 3 +} +``` + +#### Update Group + +```http +PUT /api/settings/groups/:groupId +Authorization: Bearer +Content-Type: application/json + +{ + "name": "Updated Group Name", + "description": "Updated description", + "sort_order": 2 +} +``` + +### Settings Management + +#### List All Settings + +```http +GET /api/settings +Authorization: Bearer +``` + +#### Get Settings by Group + +```http +GET /api/settings/group/:groupId +Authorization: Bearer +``` + +**Example:** + +```http +GET /api/settings/group/smtp +``` + +#### Get Specific Setting + +```http +GET /api/settings/:key +Authorization: Bearer +``` + +#### Create New Setting + +```http +POST /api/settings +Authorization: Bearer +Content-Type: application/json + +{ + "key": "smtp.password", + "value": "secret123", + "description": "SMTP server password", + "encrypted": true, + "group_id": "smtp" +} +``` + +#### Update Existing Setting + +```http +PUT /api/settings/:key +Authorization: Bearer +Content-Type: application/json + +{ + "value": "new-secret-value", + "description": "Updated SMTP password", + "encrypted": true, + "group_id": "smtp" +} +``` + +#### Delete Setting + +```http +DELETE /api/settings/:key +Authorization: Bearer +``` + +#### Search Settings + +```http +POST /api/settings/search +Authorization: Bearer +Content-Type: application/json + +{ + "pattern": "smtp" +} +``` + +#### Bulk Create/Update Settings + +```http +POST /api/settings/bulk +Authorization: Bearer +Content-Type: application/json + +{ + "settings": [ + { + "key": "smtp.host", + "value": "smtp.gmail.com", + "group_id": "smtp" + }, + { + "key": "smtp.port", + "value": "587", + "group_id": "smtp" + }, + { + "key": "smtp.password", + "value": "secret123", + "encrypted": true, + "group_id": "smtp" + } + ] +} +``` + +#### Health Check + +```http +GET /api/settings/health +Authorization: Bearer +``` + +## Helper Methods (Recommended) + +The GlobalSettings helper class provides simple, type-safe methods for retrieving setting values. These helpers are designed for common use cases where you just need the value of a setting, similar to the Email service helper methods. + +### Import the Helper Class + +```typescript +import { GlobalSettings } from '../global-settings'; +// or +import { GlobalSettings } from '../global-settings/helpers'; +``` + +### Basic Usage + +#### Get Setting Values + +```typescript +// Get a string value +const smtpHost = await GlobalSettings.get('smtp.host'); +const smtpHostWithDefault = await GlobalSettings.get('smtp.host', 'localhost'); + +// Get typed values +const maxRetries = await GlobalSettings.getNumber('system.max_retries', 3); +const debugMode = await GlobalSettings.getBoolean('system.debug', false); +const apiUrl = await GlobalSettings.getUrl('api.base_url'); +const supportEmail = await GlobalSettings.getEmail('support.email'); + +// Get required values (throws if missing) +const databaseUrl = await GlobalSettings.getRequired('database.url'); +``` + +#### Type-Safe Getters + +```typescript +// Boolean values (accepts: 'true', 'false', '1', '0', 'yes', 'no', 'on', 'off', 'enabled', 'disabled') +const maintenanceMode = await GlobalSettings.getBoolean('system.maintenance_mode', false); +const emailEnabled = await GlobalSettings.getBoolean('email.enabled', true); + +// Numeric values +const uploadLimit = await GlobalSettings.getNumber('upload.max_size_mb', 10); +const retryCount = await GlobalSettings.getInteger('api.retry_count', 3); + +// URL validation +const webhookUrl = await GlobalSettings.getUrl('webhook.endpoint'); +const callbackUrl = await GlobalSettings.getUrl('oauth.callback', 'http://localhost:3000/callback'); + +// Email validation +const adminEmail = await GlobalSettings.getEmail('admin.email'); +const fromEmail = await GlobalSettings.getEmail('smtp.from_email', 'noreply@example.com'); +``` + +#### Advanced Data Types + +```typescript +// JSON objects +interface ApiConfig { + timeout: number; + retries: number; + endpoints: string[]; +} +const apiConfig = await GlobalSettings.getJson('api.config'); + +// Arrays (comma-separated values) +const allowedDomains = await GlobalSettings.getArray('security.allowed_domains'); +const adminEmails = await GlobalSettings.getArray('admin.emails', ['admin@example.com']); +``` + +### Batch Operations + +#### Get Multiple Settings + +```typescript +// Get multiple settings at once +const settings = await GlobalSettings.getMultiple([ + 'smtp.host', + 'smtp.port', + 'smtp.username' +]); +// Returns: { 'smtp.host': 'smtp.gmail.com', 'smtp.port': '587', 'smtp.username': 'user@gmail.com' } + +// Get all settings in a group (without group prefix) +const smtpConfig = await GlobalSettings.getGroupValues('smtp'); +// Returns: { 'host': 'smtp.gmail.com', 'port': '587', 'username': 'user@gmail.com', ... } + +// Get all settings in a group (with full keys) +const smtpSettings = await GlobalSettings.getGroupValuesWithFullKeys('smtp'); +// Returns: { 'smtp.host': 'smtp.gmail.com', 'smtp.port': '587', 'smtp.username': 'user@gmail.com', ... } +``` + +### Utility Methods + +#### Check Setting Status + +```typescript +// Check if setting exists and has a value +if (await GlobalSettings.isSet('smtp.host')) { + console.log('SMTP host is configured'); +} + +// Check if setting is empty +if (await GlobalSettings.isEmpty('api.key')) { + console.log('API key needs to be configured'); +} + +// Check if setting exists in database (regardless of value) +if (await GlobalSettings.exists('feature.new_ui')) { + console.log('New UI feature flag exists'); +} +``` + +#### Error Handling + +```typescript +try { + // This will throw if the setting is missing or empty + const requiredApiKey = await GlobalSettings.getRequired('api.secret_key'); + + // Use the API key + const response = await fetch('/api/data', { + headers: { 'Authorization': `Bearer ${requiredApiKey}` } + }); +} catch (error) { + console.error('Required setting missing:', error.message); + // Handle missing configuration +} +``` + +### Real-World Examples + +#### SMTP Configuration + +```typescript +import { GlobalSettings } from '../global-settings'; + +// Simple approach using helpers +const smtpConfig = { + host: await GlobalSettings.getRequired('smtp.host'), + port: await GlobalSettings.getNumber('smtp.port', 587), + secure: await GlobalSettings.getBoolean('smtp.secure', true), + auth: { + user: await GlobalSettings.getRequired('smtp.username'), + pass: await GlobalSettings.getRequired('smtp.password'), + }, + from: { + name: await GlobalSettings.get('smtp.from_name', 'DeployStack'), + address: await GlobalSettings.get('smtp.from_email') || await GlobalSettings.getRequired('smtp.username'), + } +}; + +// Or get all SMTP settings at once +const smtpSettings = await GlobalSettings.getGroupValues('smtp'); +const smtpConfigFromGroup = { + host: smtpSettings.host, + port: parseInt(smtpSettings.port || '587'), + secure: smtpSettings.secure === 'true', + auth: { + user: smtpSettings.username, + pass: smtpSettings.password, + } +}; +``` + +#### Feature Flags + +```typescript +// Check feature flags +const features = { + newDashboard: await GlobalSettings.getBoolean('features.new_dashboard', false), + apiV2: await GlobalSettings.getBoolean('features.api_v2', false), + debugMode: await GlobalSettings.getBoolean('system.debug', false), + maintenanceMode: await GlobalSettings.getBoolean('system.maintenance', false), +}; + +if (features.maintenanceMode) { + return res.status(503).json({ error: 'System under maintenance' }); +} +``` + +#### API Configuration + +```typescript +// API service configuration +const apiConfig = { + baseUrl: await GlobalSettings.getUrl('api.base_url', 'https://api.example.com'), + timeout: await GlobalSettings.getNumber('api.timeout_ms', 30000), + retries: await GlobalSettings.getInteger('api.max_retries', 3), + apiKey: await GlobalSettings.getRequired('api.secret_key'), + allowedOrigins: await GlobalSettings.getArray('api.allowed_origins', ['localhost']), +}; + +// Use in API client +const response = await fetch(`${apiConfig.baseUrl}/data`, { + timeout: apiConfig.timeout, + headers: { + 'Authorization': `Bearer ${apiConfig.apiKey}`, + 'Content-Type': 'application/json' + } +}); +``` + +#### System Configuration + +```typescript +// System-wide settings +const systemConfig = { + maxUploadSize: await GlobalSettings.getNumber('system.max_upload_mb', 10), + sessionTimeout: await GlobalSettings.getNumber('system.session_timeout_hours', 24), + logLevel: await GlobalSettings.get('system.log_level', 'info'), + adminEmails: await GlobalSettings.getArray('system.admin_emails'), + supportEmail: await GlobalSettings.getEmail('system.support_email', 'support@example.com'), +}; +``` + +## Usage Examples (GlobalSettingsService) + +For more complex operations like creating, updating, or searching settings, use the GlobalSettingsService directly: + +### SMTP Configuration + +```typescript +import { GlobalSettingsService } from '../services/globalSettingsService'; + +// Set SMTP configuration +await GlobalSettingsService.set('smtp.host', 'smtp.gmail.com', { + group_id: 'smtp', + description: 'SMTP server hostname' +}); + +await GlobalSettingsService.set('smtp.port', '587', { + group_id: 'smtp', + description: 'SMTP server port' +}); + +await GlobalSettingsService.set('smtp.username', 'user@gmail.com', { + group_id: 'smtp', + description: 'SMTP authentication username' +}); + +await GlobalSettingsService.set('smtp.password', 'app-password', { + group_id: 'smtp', + description: 'SMTP authentication password', + encrypted: true +}); + +// Retrieve SMTP configuration by group +const smtpSettings = await GlobalSettingsService.getByGroup('smtp'); +const smtpConfig = { + host: smtpSettings.find(s => s.key === 'smtp.host')?.value, + port: parseInt(smtpSettings.find(s => s.key === 'smtp.port')?.value || '587'), + auth: { + user: smtpSettings.find(s => s.key === 'smtp.username')?.value, + pass: smtpSettings.find(s => s.key === 'smtp.password')?.value, + } +}; +``` + +### API Keys Management + +```typescript +// Store encrypted API keys +await GlobalSettingsService.set('api.openai.key', 'sk-...', { + group_id: 'api-keys', + description: 'OpenAI API key for AI integrations', + encrypted: true +}); + +await GlobalSettingsService.set('api.aws.access_key', 'AKIA...', { + group_id: 'api-keys', + description: 'AWS access key for cloud services', + encrypted: true +}); + +// Retrieve API configuration by group +const apiSettings = await GlobalSettingsService.getByGroup('api-keys'); +const openaiKey = apiSettings.find(s => s.key === 'api.openai.key')?.value; +``` + +## Auto-Initialization System + +### Overview + +The auto-initialization system automatically creates missing groups and global settings when the server starts. This ensures that all required groups and settings are available without manual configuration, while preserving existing values. + +### File-Based Setting Definitions + +Settings are defined in TypeScript files within the `src/global-settings/` directory: + +```text +src/global-settings/ +├── types.ts # Type definitions +├── index.ts # Auto-discovery service +├── smtp.ts # SMTP configuration +├── github-oauth.ts # GitHub OAuth settings +└── [custom].ts # Your custom settings +``` + +### Setting Definition Format + +Each setting file exports a `GlobalSettingsModule` with group metadata: + +```typescript +// src/global-settings/smtp.ts +import type { GlobalSettingsModule } from './types'; + +export const smtpSettings: GlobalSettingsModule = { + group: { + id: 'smtp', + name: 'SMTP Mail Settings', + description: 'Email server configuration for sending notifications', + icon: 'mail', + sort_order: 1 + }, + settings: [ + { + key: 'smtp.host', + defaultValue: '', + description: 'SMTP server hostname (e.g., smtp.gmail.com)', + encrypted: false, + required: true + }, + { + key: 'smtp.password', + defaultValue: '', + description: 'SMTP authentication password', + encrypted: true, + required: true + } + // ... more settings + ] +}; +``` + +### Startup Behavior + +When the server starts: + +1. **Discovery**: Scans `src/global-settings/` for `.ts` files +2. **Loading**: Dynamically imports each settings module +3. **Validation**: Ensures each module has the correct structure +4. **Group Creation**: Creates missing groups with metadata +5. **Database Check**: Checks which settings exist in the database +6. **Creation**: Creates missing settings with default values and group links +7. **Preservation**: Skips existing settings (non-destructive) +8. **Logging**: Reports initialization results + +### Example Startup Output + +```text +🔄 Loading global settings definitions... +📁 Found 2 setting files: smtp, github-oauth +✅ Loaded settings module: smtp (7 settings) +✅ Loaded settings module: github-oauth (5 settings) +🎉 Loaded 2 settings modules with 12 total settings +🔄 Creating 2 setting groups... +✅ Created group: smtp (SMTP Mail Settings) +✅ Created group: github-oauth (GitHub OAuth Configuration) +🔄 Initializing 12 global settings... +✅ Created setting: smtp.host +✅ Created setting: smtp.port +✅ Created setting: smtp.username +✅ Created setting: smtp.password +⏭️ Skipped existing setting: smtp.secure +✅ Created setting: github.oauth.client_id +✅ Created setting: github.oauth.client_secret +🎉 Global settings initialization complete: 6 created, 1 skipped +⚠️ Missing required settings: smtp.host, smtp.username, smtp.password +``` + +### Built-in Setting Groups + +#### SMTP Settings (Group ID: `smtp`) + +| Key | Default | Required | Encrypted | Description | +|-----|---------|----------|-----------|-------------| +| `smtp.host` | `''` | ✅ | ❌ | SMTP server hostname | +| `smtp.port` | `'587'` | ✅ | ❌ | SMTP server port | +| `smtp.username` | `''` | ✅ | ❌ | SMTP authentication username | +| `smtp.password` | `''` | ✅ | ✅ | SMTP authentication password | +| `smtp.secure` | `'true'` | ❌ | ❌ | Use SSL/TLS connection | +| `smtp.from_name` | `'DeployStack'` | ❌ | ❌ | Default sender name | +| `smtp.from_email` | `''` | ❌ | ❌ | Default sender email | + +#### GitHub OAuth Settings (Group ID: `github-oauth`) + +| Key | Default | Required | Encrypted | Description | +|-----|---------|----------|-----------|-------------| +| `github.oauth.client_id` | `''` | ❌ | ❌ | GitHub OAuth client ID | +| `github.oauth.client_secret` | `''` | ❌ | ✅ | GitHub OAuth client secret | +| `github.oauth.enabled` | `'false'` | ❌ | ❌ | Enable GitHub OAuth | +| `github.oauth.callback_url` | `'http://localhost:3000/api/auth/github/callback'` | ❌ | ❌ | OAuth callback URL | +| `github.oauth.scope` | `'user:email'` | ❌ | ❌ | OAuth requested scopes | + +#### Global Settings (Group ID: `global`) + +| Key | Default | Required | Encrypted | Description | +|-----|---------|----------|-----------|-------------| +| `global.page_url` | `'http://localhost:5173'` | ❌ | ❌ | Base URL for the application frontend | +| `global.send_mail` | `'false'` | ❌ | ❌ | Enable or disable email sending functionality | +| `global.enable_login` | `'true'` | ❌ | ❌ | Enable or disable all login functionality | +| `global.enable_email_registration` | `'true'` | ❌ | ❌ | Enable or disable email registration | +| `global.enable_swagger_docs` | `'true'` | ❌ | ❌ | Enable or disable Swagger API documentation endpoint (/documentation) | + +### Helper Methods + +The system provides helper methods for retrieving complete configurations: + +```typescript +import { GlobalSettingsInitService } from '../global-settings'; + +// Get complete SMTP configuration +const smtpConfig = await GlobalSettingsInitService.getSmtpConfiguration(); +if (smtpConfig) { + // Use smtpConfig.host, smtpConfig.port, etc. +} + +// Get complete GitHub OAuth configuration +const githubConfig = await GlobalSettingsInitService.getGitHubOAuthConfiguration(); +if (githubConfig && githubConfig.enabled) { + // Use githubConfig.clientId, githubConfig.clientSecret, etc. +} + +// Check if services are configured +const isSmtpReady = await GlobalSettingsInitService.isSmtpConfigured(); +const isGitHubReady = await GlobalSettingsInitService.isGitHubOAuthConfigured(); +``` + +### Adding New Setting Groups (Core) + +To add a new core setting group (managed directly by the application): + +1. **Create Setting File**: Add a new `.ts` file in `src/global-settings/` + +```typescript +// src/global-settings/my-service.ts +import type { GlobalSettingsModule } from './types'; + +export const myServiceSettings: GlobalSettingsModule = { + group: { + id: 'my-service', + name: 'My Service Configuration', + description: 'Settings for My Service integration', + icon: 'service', + sort_order: 3 + }, + settings: [ + { + key: 'my-service.api_key', + defaultValue: '', + description: 'API key for My Service', + encrypted: true, + required: true + }, + { + key: 'my-service.enabled', + defaultValue: 'false', + description: 'Enable My Service integration', + encrypted: false, + required: false + } + ] +}; +``` + +2. **Restart Server**: The new group and settings will be automatically discovered and initialized + +3. **Add Helper Method** (optional): Add a helper method to `GlobalSettingsInitService` + +```typescript +// In src/global-settings/index.ts +static async getMyServiceConfiguration(): Promise { + const settings = await GlobalSettingsService.getByGroup('my-service'); + + const apiKey = settings.find(s => s.key === 'my-service.api_key')?.value; + const enabled = settings.find(s => s.key === 'my-service.enabled')?.value; + + if (enabled !== 'true' || !apiKey) { + return null; + } + + return { + apiKey, + enabled: enabled === 'true' + }; +} +``` + +## Frontend Integration + +The group-based system is designed for easy frontend integration: + +### Dynamic Tab Creation + +```typescript +// Frontend can easily create tabs from groups +const response = await fetch('/api/settings/groups'); +const { data: groups } = await response.json(); + +groups.forEach(group => { + createTab({ + id: group.id, // For routing: /settings/smtp + label: group.name, // Display: "SMTP Mail Settings" + icon: group.icon, // UI icon + description: group.description, + settings: group.settings, // Tab content + sortOrder: group.sort_order + }); +}); +``` + +### Group Management + +```typescript +// Get settings for a specific tab/group +const smtpSettings = await fetch('/api/settings/group/smtp'); + +// Update a setting within a group +await fetch('/api/settings/smtp.host', { + method: 'PUT', + body: JSON.stringify({ + value: 'new-smtp-host.com', + group_id: 'smtp' + }) +}); +``` + +### System Configuration + +```typescript +// System-wide feature flags and configuration +await GlobalSettingsService.set('system.maintenance_mode', 'false', { + group_id: 'system', + description: 'Enable/disable maintenance mode' +}); + +await GlobalSettingsService.set('system.max_upload_size', '10485760', { + group_id: 'system', + description: 'Maximum file upload size in bytes (10MB)' +}); + +await GlobalSettingsService.set('system.debug_logging', 'false', { + group_id: 'system', + description: 'Enable debug logging' +}); + +// Check system configuration +const maintenanceMode = (await GlobalSettingsService.get('system.maintenance_mode'))?.value === 'true'; +const maxUploadSize = parseInt((await GlobalSettingsService.get('system.max_upload_size'))?.value || '5242880'); +``` + +## Best Practices + +### Key Naming Conventions + +- Use dot notation for hierarchy: `category.subcategory.setting` +- Use lowercase with underscores for readability: `smtp.max_retry_count` +- Be descriptive but concise: `api.openai.key` not `api.openai.api_key` +- Group related settings: `database.host`, `database.port`, `database.name` + +### Group Design + +- **Logical Grouping**: Group related settings together (e.g., all SMTP settings) +- **Clear Names**: Use descriptive group names for frontend display +- **Consistent Icons**: Use consistent iconography across groups +- **Proper Ordering**: Set sort_order to control tab display sequence + +### Setting Organization + +- **Hierarchical Keys**: Use dot notation within groups: `group.subcategory.setting` +- **Group Consistency**: Keep all related settings in the same group +- **Clear Descriptions**: Provide helpful descriptions for administrators + +### Security Guidelines + +- **Always encrypt sensitive data**: Passwords, API keys, tokens, secrets +- **Use descriptive descriptions**: Help other administrators understand the purpose +- **Group sensitive settings**: Keep all sensitive settings for a service in one group +- **Regular audits**: Review settings periodically for unused or outdated values +- **Environment separation**: Use different encryption secrets for different environments + +### Performance Considerations + +- **Cache frequently accessed settings**: Consider caching non-sensitive, frequently used settings +- **Batch operations**: Use bulk endpoints when creating multiple related settings +- **Minimize database calls**: Retrieve settings by group when you need multiple related values + +### Error Handling + +```typescript +try { + const setting = await GlobalSettingsService.get('api.openai.key'); + if (!setting) { + throw new Error('OpenAI API key not configured'); + } + // Use the setting +} catch (error) { + console.error('Failed to retrieve setting:', error); + // Handle the error appropriately +} +``` + +## Migration and Setup + +### Initial Setup + +1. **Environment Variable**: Set `DEPLOYSTACK_ENCRYPTION_SECRET` in your environment +2. **Database Migration**: Run `npm run db:generate` and restart the server +3. **Admin Access**: Ensure you have a user with `global_admin` role + +### Migrating from Category-Based System + +The new group-based system replaces the old category-based approach. The migration is handled automatically: + +1. **Database Migration**: The `category` column is renamed to `group_id` +2. **Auto-Initialization**: Groups are created automatically from setting definitions +3. **Setting Linking**: Existing settings are linked to appropriate groups + +## Plugin-Contributed Global Settings + +In addition to core global settings, plugins can also define and register their own global settings and setting groups. These are managed through the same system and are subject to the same access controls (i.e., editable by `global_admin`). + +Key points for plugin-contributed settings: + +- **Declaration**: Plugins declare global settings via a `globalSettingsExtension` property in their main class. +- **Initialization**: The `PluginManager` processes these definitions at startup, creating new groups and settings if they don't already exist. +- **Precedence**: Core global settings always take precedence. If a plugin tries to define a setting with a key that already exists (either from core or another plugin), the plugin's definition for that specific key is ignored. +- **Documentation**: For details on how plugins can define global settings, refer to the [PLUGINS.MD](PLUGINS.MD) document. + +## Helper Methods API Reference + +### GlobalSettings Class Methods + +| Method | Description | Returns | +|--------|-------------|---------| +| `get(key, defaultValue?)` | Get a setting value as string | `Promise` | +| `getString(key, defaultValue?)` | Get a setting value as string (alias) | `Promise` | +| `getBoolean(key, defaultValue?)` | Get a setting value as boolean | `Promise` | +| `getNumber(key, defaultValue?)` | Get a setting value as number | `Promise` | +| `getInteger(key, defaultValue?)` | Get a setting value as integer | `Promise` | +| `getUrl(key, defaultValue?)` | Get and validate setting as URL | `Promise` | +| `getEmail(key, defaultValue?)` | Get and validate setting as email | `Promise` | +| `getJson(key, defaultValue?)` | Get and parse setting as JSON | `Promise` | +| `getArray(key, defaultValue?)` | Get setting as array (comma-separated) | `Promise` | +| `getRequired(key)` | Get required setting (throws if missing) | `Promise` | +| `getMultiple(keys)` | Get multiple settings at once | `Promise>` | +| `getGroupValues(groupId)` | Get group settings (without prefix) | `Promise>` | +| `getGroupValuesWithFullKeys(groupId)` | Get group settings (with full keys) | `Promise>` | +| `isSet(key)` | Check if setting exists and has value | `Promise` | +| `isEmpty(key)` | Check if setting is empty | `Promise` | +| `exists(key)` | Check if setting exists in database | `Promise` | +| `getRaw(key)` | Get raw setting object with metadata | `Promise` | +| `refreshCaches()` | Refresh any cached configurations | `Promise` | + +### Boolean Value Parsing + +The `getBoolean()` method accepts these string values: + +| Value | Result | +|-------|--------| +| `'true'`, `'1'`, `'yes'`, `'on'`, `'enabled'` | `true` | +| `'false'`, `'0'`, `'no'`, `'off'`, `'disabled'` | `false` | + +### Usage Patterns + +#### Simple Value Retrieval + +```typescript +const value = await GlobalSettings.get('key.name'); +const valueWithDefault = await GlobalSettings.get('key.name', 'default'); +``` + +#### Type-Safe Retrieval + +```typescript +const isEnabled = await GlobalSettings.getBoolean('feature.enabled', false); +const maxSize = await GlobalSettings.getNumber('upload.max_size', 10); +const apiUrl = await GlobalSettings.getUrl('api.endpoint'); +``` + +#### Batch Retrieval + +```typescript +const settings = await GlobalSettings.getMultiple(['key1', 'key2', 'key3']); +const groupSettings = await GlobalSettings.getGroupValues('smtp'); +``` + +#### Validation and Checks + +```typescript +if (await GlobalSettings.isSet('api.key')) { + const apiKey = await GlobalSettings.getRequired('api.key'); +} +``` + +## REST API Reference Summary + +| Endpoint | Method | Permission | Description | +|----------|--------|------------|-------------| +| `/api/settings/groups` | GET | `settings.view` | List all groups with settings | +| `/api/settings/groups/:groupId` | GET | `settings.view` | Get specific group | +| `/api/settings/groups` | POST | `settings.edit` | Create new group | +| `/api/settings/groups/:groupId` | PUT | `settings.edit` | Update group | +| `/api/settings` | GET | `settings.view` | List all settings | +| `/api/settings/:key` | GET | `settings.view` | Get specific setting | +| `/api/settings` | POST | `settings.edit` | Create new setting | +| `/api/settings/:key` | PUT | `settings.edit` | Update setting | +| `/api/settings/:key` | DELETE | `settings.delete` | Delete setting | +| `/api/settings/group/:groupId` | GET | `settings.view` | Get settings by group | +| `/api/settings/search` | POST | `settings.view` | Search settings | +| `/api/settings/bulk` | POST | `settings.edit` | Bulk create/update | +| `/api/settings/health` | GET | `settings.view` | System health check | + +--- + +For more information about the role-based access control system, see [ROLES.md](ROLES.md). +For security details, see [SECURITY.md](SECURITY.md). diff --git a/docs/deploystack/development/backend/index.mdx b/docs/deploystack/development/backend/index.mdx new file mode 100644 index 0000000..4ce2225 --- /dev/null +++ b/docs/deploystack/development/backend/index.mdx @@ -0,0 +1,143 @@ +--- +title: Backend Development +description: Complete guide to developing and contributing to the DeployStack backend - a high-performance Node.js application built with Fastify, TypeScript, and extensible plugin architecture. +--- + +import { Card, Cards } from 'fumadocs-ui/components/card'; +import { Database, Shield, Plug, Settings, Mail, TestTube, Wrench, BookOpen } from 'lucide-react'; + +# DeployStack Backend Development + +The DeployStack backend is a modern, high-performance Node.js application built with **Fastify**, **TypeScript**, and **Drizzle ORM**. It's specifically designed for managing MCP (Model Context Protocol) server deployments with enterprise-grade features including authentication, role-based access control, and an extensible plugin system. + +## Technology Stack + +- **Framework**: Fastify for high-performance HTTP server +- **Language**: TypeScript for type safety +- **Database**: SQLite (default) or PostgreSQL with Drizzle ORM +- **Validation**: Zod for request/response validation and OpenAPI generation +- **Plugin System**: Extensible architecture with security isolation +- **Authentication**: Cookie-based sessions with role-based access control + +## Quick Start + +```bash +cd services/backend +npm install +npm run dev +``` + +The development server starts at `http://localhost:3000` with API documentation at `/documentation`. + +## Development Guides + + + } + href="/deploystack/development/backend/api" + title="API Documentation" + > + Learn how to generate OpenAPI specifications, use Swagger UI, and implement Zod validation for automatic API documentation. + + + } + href="/deploystack/development/backend/database" + title="Database Management" + > + SQLite and PostgreSQL setup, schema management, migrations, and Drizzle ORM best practices. + + + } + href="/deploystack/development/backend/plugins" + title="Plugin System" + > + Create extensible plugins with isolated routes, database extensions, and security features for custom functionality. + + + } + href="/deploystack/development/backend/global-settings" + title="Global Settings" + > + Configuration management system with encrypted storage, role-based access, and plugin extensions. + + + } + href="/deploystack/development/backend/security" + title="Security & Roles" + > + Authentication, authorization, role-based access control, and security best practices. + + + } + href="/deploystack/development/backend/mail" + title="Mail System" + > + Email service configuration, SMTP setup, template management, and transactional email sending. + + + } + href="/deploystack/development/backend/test" + title="Testing" + > + Testing strategies, examples, and best practices for backend development and API testing. + + + } + href="/deploystack/development/backend/roles" + title="Roles Management" + > + User roles, permissions system, and access control implementation details. + + + +## Project Structure + +```bash +services/backend/ +├── src/ +│ ├── routes/ # API route handlers +│ ├── db/ # Database schema and configuration +│ ├── plugin-system/ # Plugin architecture +│ ├── global-settings/ # Core settings definitions +│ ├── auth/ # Authentication utilities +│ └── server.ts # Main server configuration +├── plugins/ # Extensible plugin directory +├── persistent_data/ # Data persistence +└── drizzle/ # Database migrations +``` + +## Key Features + +### Plugin Architecture +- **Security Isolation**: Routes automatically namespaced under `/api/plugin//` +- **Database Extensions**: Plugins can safely add their own tables +- **Global Settings**: Contribute configuration options +- **Lifecycle Management**: Proper initialization and cleanup + +### API Documentation +- **Automatic Generation**: OpenAPI 3.0 specs from Zod schemas +- **Interactive Testing**: Swagger UI for API exploration +- **Type Safety**: Request/response validation with TypeScript + +### Database Management +- **Multi-Database Support**: SQLite (default) and PostgreSQL +- **Type-Safe ORM**: Drizzle ORM with full TypeScript integration +- **Migration System**: Automatic schema management +- **Plugin Extensions**: Plugins can add their own tables + +## Development Workflow + +1. **Setup**: Install dependencies and start development server +2. **Database**: Use API endpoints to initialize database +3. **Development**: Add routes, modify schemas, create plugins +4. **Testing**: Run comprehensive test suite +5. **Documentation**: Generate API specs for integration + +For detailed implementation guides, security considerations, and best practices, explore the specific documentation sections above. diff --git a/docs/deploystack/development/backend/mail.mdx b/docs/deploystack/development/backend/mail.mdx new file mode 100644 index 0000000..8a454c4 --- /dev/null +++ b/docs/deploystack/development/backend/mail.mdx @@ -0,0 +1,645 @@ +--- +title: Email Integration Documentation +description: Complete email system with Nodemailer, Pug templates, SMTP configuration, and type-safe helper methods for DeployStack Backend. +--- + +# Email Integration Documentation + +This document describes the email system integration in DeployStack, including the email service, template system, and usage examples. + +## Overview + +The email system provides a comprehensive solution for sending templated emails using: + +- **Nodemailer**: For SMTP email delivery +- **Pug Templates**: For beautiful, maintainable email templates +- **Global Settings Integration**: Automatic SMTP configuration from global settings +- **Zod Validation**: Type-safe email parameter validation +- **Template Caching**: Performance optimization for template rendering + +## Architecture + +```text +src/email/ +├── emailService.ts # Main email service with SMTP integration +├── templateRenderer.ts # Pug template compilation and rendering +├── types.ts # TypeScript interfaces and Zod schemas +├── index.ts # Module exports +└── templates/ + ├── layouts/ + │ ├── base.pug # Main email layout + │ ├── header.pug # Email header component + │ └── footer.pug # Email footer component + ├── welcome.pug # Welcome email template + ├── password-reset.pug # Password reset template + └── notification.pug # General notification template +``` + +## SMTP Configuration + +The email system automatically integrates with your existing SMTP global settings. Ensure the following settings are configured in the global settings: + +| Setting | Required | Description | +|---------|----------|-------------| +| `smtp.host` | ✅ | SMTP server hostname (e.g., smtp.gmail.com) | +| `smtp.port` | ✅ | SMTP server port (587 for TLS, 465 for SSL) | +| `smtp.username` | ✅ | SMTP authentication username | +| `smtp.password` | ✅ | SMTP authentication password (encrypted) | +| `smtp.secure` | ❌ | Use SSL/TLS connection (default: true) | +| `smtp.from_name` | ❌ | Default sender name (default: DeployStack) | +| `smtp.from_email` | ❌ | Default sender email (default: username) | + +## Basic Usage + +### Import the Email Service + +```typescript +import { EmailService } from '../email'; +// or +import EmailService from '../email'; +``` + +### Send a Basic Email + +```typescript +const result = await EmailService.sendEmail({ + to: 'user@example.com', + subject: 'Welcome to DeployStack', + template: 'welcome', + variables: { + userName: 'John Doe', + userEmail: 'user@example.com', + loginUrl: 'https://app.deploystack.com/login', + supportEmail: 'support@deploystack.com' + } +}); + +if (result.success) { + console.log('Email sent successfully:', result.messageId); +} else { + console.error('Failed to send email:', result.error); +} +``` + +### Send to Multiple Recipients + +```typescript +const result = await EmailService.sendEmail({ + to: ['user1@example.com', 'user2@example.com'], + subject: 'System Maintenance Notice', + template: 'notification', + variables: { + title: 'Scheduled Maintenance', + message: 'We will be performing system maintenance on Sunday at 2 AM UTC.', + actionUrl: 'https://status.deploystack.com', + actionText: 'View Status Page' + } +}); +``` + +## Type-Safe Helper Methods + +The email service provides type-safe helper methods for common email types: + +### Welcome Email + +```typescript +const result = await EmailService.sendWelcomeEmail({ + to: 'newuser@example.com', + userName: 'Jane Smith', + userEmail: 'newuser@example.com', + loginUrl: 'https://app.deploystack.com/login', + supportEmail: 'support@deploystack.com' // optional +}); +``` + +### Password Reset Email + +```typescript +const result = await EmailService.sendPasswordResetEmail({ + to: 'user@example.com', + userName: 'John Doe', + resetUrl: 'https://app.deploystack.com/reset-password?token=abc123', + expirationTime: '24 hours', + supportEmail: 'support@deploystack.com' // optional +}); +``` + +### Notification Email + +```typescript +const result = await EmailService.sendNotificationEmail({ + to: 'user@example.com', + title: 'Deployment Complete', + message: 'Your application has been successfully deployed to production.', + actionUrl: 'https://app.deploystack.com/deployments/123', + actionText: 'View Deployment', + userName: 'John Doe' // optional +}); +``` + +## Advanced Usage + +### Custom From Address + +```typescript +const result = await EmailService.sendEmail({ + to: 'user@example.com', + subject: 'Custom Sender Example', + template: 'notification', + from: { + name: 'DeployStack Notifications', + email: 'notifications@deploystack.com' + }, + variables: { + title: 'Custom Message', + message: 'This email is sent from a custom sender.' + } +}); +``` + +### Email with Attachments + +```typescript +const result = await EmailService.sendEmail({ + to: 'user@example.com', + subject: 'Report Attached', + template: 'notification', + variables: { + title: 'Monthly Report', + message: 'Please find your monthly deployment report attached.' + }, + attachments: [ + { + filename: 'report.pdf', + content: reportBuffer, + contentType: 'application/pdf' + } + ] +}); +``` + +### CC and BCC Recipients + +```typescript +const result = await EmailService.sendEmail({ + to: 'primary@example.com', + cc: ['manager@example.com'], + bcc: ['audit@example.com'], + subject: 'Important Update', + template: 'notification', + variables: { + title: 'System Update', + message: 'Important system update notification.' + } +}); +``` + +## Template System + +### Available Templates + +| Template | Description | Required Variables | +|----------|-------------|-------------------| +| `welcome` | Welcome email for new users | `userName`, `userEmail`, `loginUrl` | +| `password-reset` | Password reset instructions | `userName`, `resetUrl`, `expirationTime` | +| `notification` | General notification template | `title`, `message` | + +### Template Variables + +All templates have access to these common variables: + +- `currentYear`: Current year (automatically injected) +- `appName`: Application name (default: 'DeployStack') +- `supportEmail`: Support email address (if provided) + +### Creating Custom Templates + +1. **Create a new Pug template** in `src/email/templates/`: + +```pug +//- custom-template.pug +//- @description Custom email template +//- @variables customVar1, customVar2 +extends layouts/base.pug + +block content + h1 Custom Email + + p Hello #{customVar1}! + + p= customVar2 + + .text-center + a.button(href="https://example.com") Take Action +``` + +2. **Add TypeScript types** in `src/email/types.ts`: + +```typescript +export interface CustomEmailVariables { + customVar1: string; + customVar2: string; +} + +// Add to TemplateVariableMap +export interface TemplateVariableMap { + welcome: WelcomeEmailVariables; + 'password-reset': PasswordResetEmailVariables; + notification: NotificationEmailVariables; + 'custom-template': CustomEmailVariables; // Add this line +} +``` + +3. **Use the custom template**: + +```typescript +const result = await EmailService.sendEmail({ + to: 'user@example.com', + subject: 'Custom Email', + template: 'custom-template', + variables: { + customVar1: 'John', + customVar2: 'This is a custom message.' + } +}); +``` + +## Template Layout System + +### Base Layout + +The base layout (`layouts/base.pug`) provides: + +- Responsive HTML email structure +- Cross-client CSS compatibility +- Header and footer inclusion +- Mobile-friendly design +- Professional styling + +### Header Component + +The header (`layouts/header.pug`) displays: + +- Application name/logo +- Consistent branding +- Professional appearance + +### Footer Component + +The footer (`layouts/footer.pug`) includes: + +- Copyright information +- Contact information +- Unsubscribe/support links +- Legal disclaimers + +### Customizing Layouts + +To customize the layout, modify the files in `src/email/templates/layouts/`: + +```pug +//- layouts/header.pug +.header + img(src="https://your-domain.com/logo.png" alt="Your Logo" style="height: 40px;") + h1= appName || 'Your App Name' +``` + +## Utility Methods + +### Test SMTP Connection + +```typescript +const status = await EmailService.testConnection(); +if (status.success) { + console.log('SMTP connection successful'); +} else { + console.error('SMTP connection failed:', status.error); +} +``` + +### Check SMTP Configuration + +```typescript +const status = await EmailService.getSmtpStatus(); +if (status.configured) { + console.log('SMTP is configured'); +} else { + console.error('SMTP not configured:', status.error); +} +``` + +### Refresh Configuration + +```typescript +// Call this after updating SMTP settings +await EmailService.refreshConfiguration(); +``` + +### Get Available Templates + +```typescript +const templates = EmailService.getAvailableTemplates(); +console.log('Available templates:', templates); +// Output: ['welcome', 'password-reset', 'notification'] +``` + +### Validate Template + +```typescript +const validation = await EmailService.validateTemplate('welcome', { + userName: 'John', + userEmail: 'john@example.com', + loginUrl: 'https://app.com/login' +}); + +if (validation.valid) { + console.log('Template is valid'); +} else { + console.error('Template validation failed:', validation.errors); +} +``` + +## Error Handling + +The email service provides comprehensive error handling: + +```typescript +const result = await EmailService.sendEmail({ + to: 'invalid-email', + subject: 'Test', + template: 'welcome', + variables: { userName: 'Test' } +}); + +if (!result.success) { + switch (result.error) { + case 'SMTP configuration is not available or invalid': + // Handle SMTP configuration issues + break; + case 'Template \'welcome\' not found': + // Handle missing template + break; + default: + // Handle other errors + console.error('Email failed:', result.error); + } +} +``` + +## Performance Considerations + +### Template Caching + +Templates are automatically cached after first compilation: + +```typescript +// First call compiles and caches the template +await EmailService.sendEmail({ template: 'welcome', ... }); + +// Subsequent calls use cached template (faster) +await EmailService.sendEmail({ template: 'welcome', ... }); +``` + +### Clear Cache (Development) + +```typescript +import { TemplateRenderer } from '../email'; + +// Clear template cache during development +TemplateRenderer.clearCache(); +``` + +### Connection Pooling + +The email service uses connection pooling for better performance: + +- Maximum 5 concurrent connections +- Maximum 100 messages per connection +- Rate limiting: 5 emails per 20 seconds + +## Security Best Practices + +### Input Validation + +All email parameters are validated using Zod schemas: + +```typescript +// This will throw a validation error +await EmailService.sendEmail({ + to: 'invalid-email-format', // ❌ Invalid email + subject: '', // ❌ Empty subject + template: '', // ❌ Empty template + variables: {} +}); +``` + +### Template Security + +- Templates are compiled server-side (no client-side execution) +- Variable injection is escaped by default +- No arbitrary code execution in templates + +### SMTP Security + +- Passwords are encrypted in global settings +- Secure connections (TLS/SSL) are supported +- Connection pooling with rate limiting + +## Integration Examples + +### User Registration + +```typescript +// In your user registration service +import { EmailService } from '../email'; + +export class UserService { + static async registerUser(userData: UserRegistrationData) { + // Create user account + const user = await this.createUser(userData); + + // Send welcome email + const emailResult = await EmailService.sendWelcomeEmail({ + to: user.email, + userName: user.name, + userEmail: user.email, + loginUrl: `${process.env.FRONTEND_URL}/login`, + supportEmail: 'support@deploystack.com' + }); + + if (!emailResult.success) { + console.error('Failed to send welcome email:', emailResult.error); + // Don't fail registration if email fails + } + + return user; + } +} +``` + +### Password Reset Flow + +```typescript +// In your auth service +import { EmailService } from '../email'; + +export class AuthService { + static async requestPasswordReset(email: string) { + const user = await this.findUserByEmail(email); + if (!user) { + throw new Error('User not found'); + } + + // Generate reset token + const resetToken = await this.generateResetToken(user.id); + const resetUrl = `${process.env.FRONTEND_URL}/reset-password?token=${resetToken}`; + + // Send reset email + const emailResult = await EmailService.sendPasswordResetEmail({ + to: user.email, + userName: user.name, + resetUrl, + expirationTime: '24 hours', + supportEmail: 'support@deploystack.com' + }); + + if (!emailResult.success) { + throw new Error('Failed to send password reset email'); + } + + return { message: 'Password reset email sent' }; + } +} +``` + +### Deployment Notifications + +```typescript +// In your deployment service +import { EmailService } from '../email'; + +export class DeploymentService { + static async notifyDeploymentComplete(deploymentId: string) { + const deployment = await this.getDeployment(deploymentId); + const user = await this.getUser(deployment.userId); + + const emailResult = await EmailService.sendNotificationEmail({ + to: user.email, + title: 'Deployment Complete', + message: `Your deployment "${deployment.name}" has been successfully completed.`, + actionUrl: `${process.env.FRONTEND_URL}/deployments/${deploymentId}`, + actionText: 'View Deployment', + userName: user.name + }); + + if (!emailResult.success) { + console.error('Failed to send deployment notification:', emailResult.error); + } + } +} +``` + +## Troubleshooting + +### Common Issues + +1. **SMTP Configuration Not Found** + + ```text + Error: SMTP configuration is not complete. Please configure SMTP settings in global settings. + ``` + + **Solution**: Configure SMTP settings in the global settings interface. + +2. **Template Not Found** + + ```text + Error: Template 'welcome' not found at /path/to/templates/welcome.pug + ``` + + **Solution**: Ensure the template file exists in the templates directory. + +3. **Invalid Email Address** + + ```text + Error: Invalid email address + ``` + + **Solution**: Validate email addresses before sending. + +4. **SMTP Connection Failed** + + ```text + Error: Connection timeout + ``` + + **Solution**: Check SMTP server settings and network connectivity. + +### Debug Mode + +Enable debug logging for email operations: + +```typescript +// Set environment variable +process.env.DEBUG_EMAIL = 'true'; + +// Or log email results +const result = await EmailService.sendEmail({...}); +console.log('Email result:', result); +``` + +### Testing SMTP Configuration + +```typescript +// Test SMTP connection before sending emails +const connectionTest = await EmailService.testConnection(); +if (!connectionTest.success) { + console.error('SMTP test failed:', connectionTest.error); + return; +} + +// Proceed with sending emails +const emailResult = await EmailService.sendEmail({...}); +``` + +## Best Practices + +1. **Always handle email failures gracefully** - Don't let email failures break your main application flow +2. **Use type-safe helper methods** when possible for better developer experience +3. **Test email templates** in different email clients for compatibility +4. **Monitor email delivery** and set up alerts for failures +5. **Use meaningful subject lines** and clear call-to-action buttons +6. **Respect user preferences** for email notifications +7. **Keep templates simple** and mobile-friendly +8. **Cache templates** in production for better performance + +## API Reference + +### EmailService Methods + +| Method | Description | Returns | +|--------|-------------|---------| +| `sendEmail(options)` | Send an email using a template | `Promise` | +| `sendWelcomeEmail(options)` | Send a welcome email | `Promise` | +| `sendPasswordResetEmail(options)` | Send a password reset email | `Promise` | +| `sendNotificationEmail(options)` | Send a notification email | `Promise` | +| `testConnection()` | Test SMTP connection | `Promise<{success: boolean, error?: string}>` | +| `getSmtpStatus()` | Check SMTP configuration status | `Promise<{configured: boolean, error?: string}>` | +| `refreshConfiguration()` | Reload SMTP configuration | `Promise` | +| `getAvailableTemplates()` | Get list of available templates | `string[]` | +| `validateTemplate(template, variables)` | Validate template and variables | `Promise` | + +### TemplateRenderer Methods + +| Method | Description | Returns | +|--------|-------------|---------| +| `render(options)` | Render a template with variables | `Promise` | +| `validateTemplate(template, variables)` | Validate template | `Promise` | +| `getAvailableTemplates()` | Get available templates | `string[]` | +| `clearCache()` | Clear template cache | `void` | +| `getTemplateMetadata(template)` | Get template metadata | `{description?: string, requiredVariables?: string[]}` | + +--- + +For more information about global settings configuration, see [GLOBAL_SETTINGS.md](GLOBAL_SETTINGS.md). diff --git a/docs/deploystack/development/backend/meta.json b/docs/deploystack/development/backend/meta.json new file mode 100644 index 0000000..9c11ef8 --- /dev/null +++ b/docs/deploystack/development/backend/meta.json @@ -0,0 +1,4 @@ +{ + "title": "Backend Development", + "description": "Complete guide to developing the DeployStack backend application" +} diff --git a/docs/deploystack/development/backend/plugins.mdx b/docs/deploystack/development/backend/plugins.mdx new file mode 100644 index 0000000..a934faf --- /dev/null +++ b/docs/deploystack/development/backend/plugins.mdx @@ -0,0 +1,602 @@ +--- +title: DeployStack Plugin System +description: Comprehensive guide to creating extensible plugins with database tables, isolated API routes, and security features for DeployStack Backend development. +--- + +# DeployStack Plugin System + +This document explains how to create and integrate plugins into DeployStack. The plugin system enables extending DeployStack with additional functionality, cloud providers, database tables, APIs, and UI components. + +## Overview + +DeployStack's plugin architecture allows for extensible, modular development with built-in security and isolation. Plugins can: + +- Add new database tables and schemas +- Register new API routes (automatically namespaced for security) +- Extend core functionality +- Add support for additional cloud providers +- Implement custom business logic +- Define global settings and configuration groups + +## Security Features + +### Route Isolation & Security + +DeployStack implements strict route isolation to ensure plugins cannot interfere with core functionality or each other: + +- **Automatic Namespacing**: All plugin routes are automatically prefixed with `/api/plugin//` +- **No Direct Route Access**: Plugins cannot register routes directly on the global Fastify instance +- **Sandboxed Registration**: Plugins use `PluginRouteManager` which enforces namespacing +- **Core Route Protection**: Plugins cannot access or modify core routes (`/api/auth/*`, `/api/users/*`, etc.) + +### Security Benefits + +1. **Prevents Route Hijacking**: Malicious plugins cannot override authentication or user management routes +2. **Eliminates Route Conflicts**: Multiple plugins cannot register conflicting routes +3. **Predictable API Surface**: All plugin APIs follow consistent `/api/plugin//` structure +4. **Easy Auditing**: Route ownership is immediately clear from the URL structure +5. **Fail-Safe Design**: Plugins that don't follow the new system simply won't have routes registered + +### Example Security Enforcement + +```typescript +// ❌ This will NOT work - no direct app access +async initialize(app: FastifyInstance, db: AnyDatabase | null) { + app.get('/api/auth/bypass', handler); // Cannot access core routes +} + +// ✅ This is the ONLY way to register routes +async registerRoutes(routeManager: PluginRouteManager, db: AnyDatabase | null) { + // Automatically becomes /api/plugin/my-plugin/data + routeManager.get('/data', handler); +} +``` + +## Plugin Structure + +A basic plugin consists of the following files: + +```bash +your-plugin/ +├── package.json # Plugin metadata +├── index.ts # Main plugin entry point (metadata, DB extensions, global settings) +├── routes.ts # API route definitions (isolated and namespaced) +└── schema.ts # Optional database schema extensions +``` + +### Required Files + +1. **package.json** - Defines plugin metadata and dependencies +2. **index.ts** - Implements the Plugin interface and exports the plugin class +3. **routes.ts** - Contains all API route definitions (automatically namespaced) +4. **schema.ts** - (Optional) Contains database schema extensions + +### File Responsibilities + +- **index.ts**: Plugin metadata, database extensions, global settings, non-route initialization +- **routes.ts**: All API route definitions using the isolated `PluginRouteManager` +- **schema.ts**: Database table definitions and schema extensions +- **package.json**: Plugin metadata and dependency declarations + +## Creating a New Plugin + +### 1. Create Plugin Directory + +Create a directory for your plugin: + +```bash +mkdir -p plugins/my-custom-plugin +cd plugins/my-custom-plugin +``` + +### 2. Create package.json + +Add basic plugin information: + +```json +{ + "name": "deploystack-my-custom-plugin", + "version": "1.0.0", + "main": "index.js", + "private": true +} +``` + +### 3. Define Database Schema (Optional) + +If your plugin requires database tables, create a `schema.ts` file: + +```typescript +import { sqliteTable, text, integer, sql } from 'drizzle-orm/sqlite-core'; + +// Define your plugin's tables +export const myCustomEntities = sqliteTable('my_custom_entities', { + id: text('id').primaryKey(), + name: text('name').notNull(), + data: text('data'), + createdAt: integer('created_at', { mode: 'timestamp' }).notNull().default(sql`(strftime('%s', 'now'))`), +}); + +// You can define multiple tables if needed +export const myCustomRelations = sqliteTable('my_custom_relations', { + id: text('id').primaryKey(), + entityId: text('entity_id').notNull().references(() => myCustomEntities.id), + relationType: text('relation_type').notNull(), +}); +``` + +### 4. Create Routes File + +Create a `routes.ts` file for your API routes: + +```typescript +import { type PluginRouteManager } from '../../plugin-system/route-manager'; +import { type AnyDatabase, getSchema } from '../../db'; +import { type BetterSQLite3Database } from 'drizzle-orm/better-sqlite3'; +import { type NodePgDatabase } from 'drizzle-orm/node-postgres'; +import { type SQLiteTable } from 'drizzle-orm/sqlite-core'; +import { type PgTable } from 'drizzle-orm/pg-core'; +import { eq } from 'drizzle-orm'; + +// Helper type guard for database type checking +function isSQLiteDB(db: AnyDatabase): db is BetterSQLite3Database { + return typeof (db as BetterSQLite3Database).get === 'function' && + typeof (db as BetterSQLite3Database).all === 'function' && + typeof (db as BetterSQLite3Database).run === 'function'; +} + +/** + * Register all routes for your custom plugin + * + * All routes registered here will be automatically namespaced under: + * /api/plugin/my-custom-plugin/ + */ +export async function registerRoutes(routeManager: PluginRouteManager, db: AnyDatabase | null): Promise { + if (!db) { + console.warn(`[${routeManager.getPluginId()}] Database not available, skipping routes.`); + return; + } + + const currentSchema = getSchema(); + const tableNameInSchema = `${routeManager.getPluginId()}_my_custom_entities`; + const table = currentSchema[tableNameInSchema]; + + if (!table) { + console.error(`[${routeManager.getPluginId()}] Table ${tableNameInSchema} not found in schema!`); + return; + } + + // Register GET /entities route + // This becomes: GET /api/plugin/my-custom-plugin/entities + routeManager.get('/entities', async () => { + if (isSQLiteDB(db)) { + const entities = await db.select().from(table as SQLiteTable).all(); + return { entities }; + } else { + const entities = await (db as NodePgDatabase).select().from(table as PgTable); + return { entities }; + } + }); + + // Register GET /entities/:id route + // This becomes: GET /api/plugin/my-custom-plugin/entities/:id + routeManager.get('/entities/:id', async (request, reply) => { + const { id } = request.params as { id: string }; + let entity; + + if (isSQLiteDB(db)) { + const typedTable = table as SQLiteTable & { id: any }; + entity = await db + .select() + .from(typedTable) + .where(eq(typedTable.id, id)) + .get(); + } else { + const typedTable = table as PgTable & { id: any }; + const rows = await (db as NodePgDatabase) + .select() + .from(typedTable) + .where(eq(typedTable.id, id)); + entity = rows[0] ?? null; + } + + if (!entity) { + return reply.status(404).send({ error: 'Entity not found' }); + } + return entity; + }); + + // Register POST /entities route + // This becomes: POST /api/plugin/my-custom-plugin/entities + routeManager.post('/entities', async (request, reply) => { + const body = request.body as { name: string; data?: string }; + + if (!body.name) { + return reply.status(400).send({ error: 'Name is required' }); + } + + const id = crypto.randomUUID(); + const entityData = { + id, + name: body.name, + data: body.data || null, + }; + + if (isSQLiteDB(db)) { + await db.insert(table as SQLiteTable).values(entityData).run(); + } else { + await (db as NodePgDatabase).insert(table as PgTable).values(entityData); + } + + return { id, ...body }; + }); + + console.log(`[${routeManager.getPluginId()}] Routes registered successfully under ${routeManager.getNamespace()}`); +} +``` + +### 5. Implement the Plugin Interface + +Create an `index.ts` file that implements the Plugin interface: + +```typescript +import { + type Plugin, + type DatabaseExtension, + type PluginRouteManager +} from '../../plugin-system/types'; +import { type AnyDatabase, getSchema } from '../../db'; +import { type BetterSQLite3Database } from 'drizzle-orm/better-sqlite3'; +import { type NodePgDatabase } from 'drizzle-orm/node-postgres'; +import { type SQLiteTable } from 'drizzle-orm/sqlite-core'; +import { type PgTable } from 'drizzle-orm/pg-core'; +import { sql } from 'drizzle-orm'; + +// Helper type guard for database type checking +function isSQLiteDB(db: AnyDatabase): db is BetterSQLite3Database { + return typeof (db as BetterSQLite3Database).get === 'function' && + typeof (db as BetterSQLite3Database).all === 'function' && + typeof (db as BetterSQLite3Database).run === 'function'; +} + +// Table definitions for this plugin +const myCustomPluginTableDefinitions = { + 'my_custom_entities': { + id: (b: any) => b('id').primaryKey(), + name: (b: any) => b('name').notNull(), + data: (b: any) => b('data'), + createdAt: (b: any) => b('created_at', { mode: 'timestamp' }).notNull().defaultNow(), + } +}; + +class MyCustomPlugin implements Plugin { + // Plugin metadata + meta = { + id: 'my-custom-plugin', + name: 'My Custom Plugin', + version: '1.0.0', + description: 'Adds custom functionality to DeployStack', + author: 'Your Name', + }; + + // Database extension (optional - remove if not needed) + databaseExtension: DatabaseExtension = { + tableDefinitions: myCustomPluginTableDefinitions, + + // Optional initialization function for seeding data + onDatabaseInit: async (db: AnyDatabase) => { + console.log(`[${this.meta.id}] Initializing database...`); + + const currentSchema = getSchema(); + const tableNameInSchema = `${this.meta.id}_my_custom_entities`; + const table = currentSchema[tableNameInSchema]; + + if (!table) { + console.error(`[${this.meta.id}] Table ${tableNameInSchema} not found in schema!`); + return; + } + + let currentCount = 0; + if (isSQLiteDB(db)) { + const result = await db + .select({ count: sql`count(*)` }) + .from(table as SQLiteTable) + .get(); + currentCount = result?.count ?? 0; + } else { + const rows = await (db as NodePgDatabase) + .select({ count: sql`count(*)` }) + .from(table as PgTable); + currentCount = rows[0]?.count ?? 0; + } + + if (currentCount === 0) { + console.log(`[${this.meta.id}] Seeding initial data...`); + const dataToSeed = { + id: 'initial-entity', + name: 'Initial Entity', + data: JSON.stringify({ initialized: true }), + }; + + if (isSQLiteDB(db)) { + await db.insert(table as SQLiteTable).values(dataToSeed).run(); + } else { + await (db as NodePgDatabase).insert(table as PgTable).values(dataToSeed); + } + console.log(`[${this.meta.id}] Seeded initial data`); + } + }, + }; + + // Plugin initialization (non-route initialization only) + async initialize(db: AnyDatabase | null) { + console.log(`[${this.meta.id}] Initializing...`); + // Non-route initialization only - routes are registered via registerRoutes method + console.log(`[${this.meta.id}] Initialized successfully`); + } + + // Register plugin routes using the isolated route manager + async registerRoutes(routeManager: PluginRouteManager, db: AnyDatabase | null) { + const { registerRoutes } = await import('./routes'); + await registerRoutes(routeManager, db); + } + + // Optional shutdown method for cleanup + async shutdown() { + console.log(`[${this.meta.id}] Shutting down...`); + // Perform any cleanup needed + } +} + +// Export the plugin class as default +export default MyCustomPlugin; +``` + +## Plugin Integration Points + +### Database Extension + +The `databaseExtension` property allows your plugin to: + +1. Define tables using Drizzle ORM +2. Initialize data (seeding, migrations, etc.) +3. Integrate with the core database schema + +### API Routes + +Register API routes during the plugin's `initialize` method: + +```typescript +app.get('/api/my-feature', async (request, reply) => { + // Handle request + return { feature: 'data' }; +}); +``` + +### Access to Core Services + +Plugins receive access to: + +- **Fastify instance** (`app`) - For registering routes, hooks, and decorations +- **Database instance** (`db`) - For database operations +- **Configuration** - Through the plugin manager (if provided) +- **Global Settings** - Plugins can define their own global settings + +## Plugin Lifecycle + +Plugins follow this lifecycle: + +1. **Loading** - Plugin is discovered and loaded +2. **Database Registration** - Schema tables are registered +3. **Database Initialization** - `onDatabaseInit` is called if provided +4. **Initialization** - `initialize` method is called +5. **Runtime** - Plugin operates as part of the application +6. **Shutdown** - `shutdown` method is called during application termination + +## Testing Your Plugin + +To test your plugin: + +1. Place it in the `plugins` directory +2. Start the DeployStack server +3. Check server logs for initialization messages +4. Test your plugin's API endpoints + +## Advanced Plugin Features + +### Configuration + +Your plugin can access configuration provided by the plugin manager: + +```typescript +async initialize(app: FastifyInstance, db: BetterSQLite3Database) { + // Access plugin-specific configuration + const config = app.pluginManager.getPluginConfig(this.meta.id); + + // Use configuration values + const apiKey = config?.apiKey as string; + + // Initialize with configuration +} +``` + +### Plugin Manager APIs + +Plugins can access other plugins through the plugin manager: + +```typescript +// Check if another plugin is available +const hasAnotherPlugin = app.pluginManager.getPlugin('another-plugin-id'); + +// Conditionally use functionality if available +if (hasAnotherPlugin) { + // Integrate with the other plugin +} +``` + +### Frontend Integration + +If your plugin needs to extend the UI, you can: + +1. Register API endpoints that provide UI configuration +2. Use the Plugin Manager to register UI components +3. Follow frontend plugin documentation for UI extensions + +## Best Practices + +1. **Unique IDs** - Ensure your plugin ID is unique and descriptive +2. **Error Handling** - Properly handle errors in your plugin +3. **Database Relationships** - Be careful with cross-plugin table relationships +4. **Schema Design** - Follow naming conventions for your plugin's tables +5. **Documentation** - Include a README.md with your plugin +6. **Versioning** - Use semantic versioning for your plugin + +## Troubleshooting + +### Plugin Not Loading + +- Check plugin directory structure +- Ensure your plugin class is exported as default +- Verify package.json contains required fields + +### Database Errors + +- Check your schema definitions +- Ensure proper initialization in `onDatabaseInit` +- Verify SQL queries in your plugin + +### Integration Issues + +- Look for errors during plugin initialization +- Check console logs for error messages +- Verify API routes are registered correctly + +## Example Plugins + +See the `plugins/example-plugin` directory for a working example. + +## Plugin API Reference + +The complete Plugin interface is defined in `src/plugin-system/types.ts`. + +## Defining Global Settings via Plugins + +Plugins can contribute their own global settings to the DeployStack system. These settings will be managed alongside core global settings and will be editable by users with the `global_admin` role. + +### How it Works + +1. **Define `globalSettingsExtension`**: In your plugin class, add an optional property `globalSettingsExtension`. +2. **Structure**: This property should be an object implementing the `GlobalSettingsExtension` interface (defined in `src/plugin-system/types.ts`). It can contain: + +- `groups`: An optional array of `GlobalSettingGroupForPlugin` objects to define new setting groups. +- `settings`: A mandatory array of `GlobalSettingDefinitionForPlugin` objects to define individual settings. + +3. **Initialization**: During server startup, the `PluginManager` will: + +- Collect all group and setting definitions from active plugins. +- Create any new groups defined by plugins if they don't already exist. If a group ID already exists, the plugin's group definition is ignored for that specific group, and the existing group is used. +- Initialize the plugin's global settings with their default values, but only if a setting with the same key doesn't already exist (either from core settings or another plugin). Core settings always take precedence. + +4. **Access Control**: All plugin-defined global settings are subject to the same access control as core settings (i.e., manageable by `global_admin`). + +5. **Security**: + +- **Core Precedence**: Core global settings (defined in `services/backend/src/global-settings/`) cannot be overridden by plugins. +- **Duplicate Keys**: If a plugin attempts to register a setting with a key that already exists (from core or another plugin), the plugin's setting will be ignored, and a warning will be logged. + +### Example: Defining Global Settings in a Plugin + +```typescript +// In your plugin's index.ts + +import { + type Plugin, + type GlobalSettingsExtension, + // ... other imports +} from '../../plugin-system/types'; + +class MyAwesomePlugin implements Plugin { + meta = { + id: 'my-awesome-plugin', + name: 'My Awesome Plugin', + version: '1.0.0', + // ... other metadata + }; + + globalSettingsExtension: GlobalSettingsExtension = { + groups: [ + { + id: 'my_awesome_plugin_group', // Unique ID for the group + name: 'My Awesome Plugin Config', + description: 'Settings specific to My Awesome Plugin.', + icon: 'settings-2', // Example: Lucide icon name + sort_order: 150, // Controls tab order in UI + } + ], + settings: [ + { + key: 'myAwesomePlugin.features.enableSuperFeature', + defaultValue: true, + type: 'boolean', + description: 'Enables the super feature of this plugin.', + encrypted: false, + required: false, + groupId: 'my_awesome_plugin_group', // Link to the group defined above + }, + { + key: 'myAwesomePlugin.credentials.externalApiKey', + defaultValue: '', + type: 'string', + description: 'API key for an external service used by this plugin.', + encrypted: true, // Sensitive value, will be encrypted + required: true, + groupId: 'my_awesome_plugin_group', + }, + { + key: 'myAwesomePlugin.performance.maxRetries', + defaultValue: 5, + type: 'number', + description: 'Maximum number of retries for API calls.', + encrypted: false, + required: false, + groupId: 'my_awesome_plugin_group', + }, + { + // Example of a setting not belonging to a new custom group + // It might appear in a default group or ungrouped in the UI, + // or you can assign it to an existing core group ID if appropriate. + key: 'myAwesomePlugin.performance.cacheDurationSeconds', + defaultValue: 3600, + type: 'number', + description: 'Cache duration in seconds for plugin data.', + encrypted: false, + required: false, + // groupId: 'system', // Example: if you want to add to an existing core group + } + ] + }; + + // ... rest of your plugin implementation (databaseExtension, initialize, etc.) + async initialize(app: FastifyInstance, db: AnyDatabase | null) { + console.log(`[${this.meta.id}] Initializing...`); + + // You can try to access your plugin's settings here if needed during init, + // using GlobalSettingsService.get('myAwesomePlugin.features.enableSuperFeature') + // Note: Ensure GlobalSettingsService is available or handle potential errors. + } +} + +export default MyAwesomePlugin; +``` + +### Important Considerations + +- **Key Uniqueness**: Ensure your setting keys are unique, preferably prefixed with your plugin ID (e.g., `yourPluginId.category.settingName`) to avoid conflicts. +- **Group IDs**: If defining new groups, ensure their IDs are unique. +- **Default Values**: Provide sensible default values. +- **Encryption**: Mark sensitive settings (API keys, passwords) with `encrypted: true`. +- **Documentation**: Document any global settings your plugin introduces in its own README or documentation. + +--- + +For additional questions or support, please contact the DeployStack team or open an issue on GitHub. diff --git a/docs/deploystack/development/backend/roles.mdx b/docs/deploystack/development/backend/roles.mdx new file mode 100644 index 0000000..55b9004 --- /dev/null +++ b/docs/deploystack/development/backend/roles.mdx @@ -0,0 +1,693 @@ +--- +title: Role-Based Access Control System +description: Complete RBAC implementation with roles, permissions, team management, and security features for DeployStack Backend development. +--- + +# Role-Based Access Control System + +This document describes the role-based access control (RBAC) system implemented in the DeployStack backend. + +## Overview + +The RBAC system provides fine-grained access control through roles and permissions. It supports: + +- **Global Roles**: System-wide roles that control access to administrative functions +- **Permission-Based Access**: Granular permissions for specific actions +- **Extensible Design**: Easy to add new roles and permissions +- **Secure Defaults**: Safe fallbacks and protection against privilege escalation + +## Default Roles + +### Global Administrator (`global_admin`) + +- **Description**: Full system access with user management capabilities +- **Permissions**: + - `users.list` - List all users + - `users.view` - View user details + - `users.edit` - Edit user information + - `users.delete` - Delete users + - `users.create` - Create new users + - `roles.manage` - Manage roles and permissions + - `system.admin` - Administrative system access + - `settings.view` - View global application settings + - `settings.edit` - Create and update global application settings + - `settings.delete` - Delete global application settings + - `teams.create` - Create new teams + - `teams.view` - View team details + - `teams.edit` - Edit team settings + - `teams.delete` - Delete teams + - `teams.manage` - Full team management + - `team.members.view` - View team members + - `team.members.manage` - Manage team member roles + +### Global User (`global_user`) + +- **Description**: Standard user with basic profile access +- **Permissions**: + - `profile.view` - View own profile + - `profile.edit` - Edit own profile + - `teams.create` - Create new teams (up to 3) + - `teams.view` - View team details + - `teams.edit` - Edit own team settings + - `teams.delete` - Delete own teams + - `team.members.view` - View team members + +### Team Administrator (`team_admin`) + +- **Description**: Full management access within a specific team +- **Permissions**: + - `teams.view` - View team details + - `teams.edit` - Edit team settings + - `teams.delete` - Delete team (if owner) + - `teams.manage` - Full team management + - `team.members.view` - View team members + - `team.members.manage` - Manage team member roles + +### Team User (`team_user`) + +- **Description**: Basic team member with limited access +- **Permissions**: + - `teams.view` - View team details + - `team.members.view` - View team members + +## Team System + +DeployStack includes a comprehensive team management system that allows users to organize their work into teams. Each user automatically gets their own team upon registration and can create up to 3 teams total. + +### Team Features + +- **Automatic Team Creation**: Every new user gets a default team created with their username +- **Team Ownership**: Each team has an owner who has full administrative control +- **Single User Teams**: Currently, teams support only one user per team +- **Team Limits**: Users can create up to 3 teams maximum +- **Unique Slugs**: Teams have URL-friendly slugs with automatic conflict resolution + +### Team Database Schema + +#### Teams Table + +```sql +CREATE TABLE teams ( + id TEXT PRIMARY KEY, + name TEXT NOT NULL, + slug TEXT NOT NULL UNIQUE, + description TEXT, + owner_id TEXT NOT NULL REFERENCES authUser(id) ON DELETE CASCADE, + created_at INTEGER NOT NULL, + updated_at INTEGER NOT NULL +); +``` + +#### Team Memberships Table + +```sql +CREATE TABLE teamMemberships ( + id TEXT PRIMARY KEY, + team_id TEXT NOT NULL REFERENCES teams(id) ON DELETE CASCADE, + user_id TEXT NOT NULL REFERENCES authUser(id) ON DELETE CASCADE, + role TEXT NOT NULL, -- 'team_admin' or 'team_user' + joined_at INTEGER NOT NULL, + UNIQUE(team_id, user_id) +); +``` + +### Team Registration Flow + +When a user registers: + +1. User account is created with appropriate global role +2. A default team is automatically created using the user's username +3. The user is added as `team_admin` of their new team +4. If username conflicts exist, slug gets incremented (e.g., `john-doe-2`) + +### Team Management + +#### Team Creation + +- Users can create up to 3 teams +- Team names are converted to URL-friendly slugs +- Automatic conflict resolution for duplicate slugs +- Team owner becomes `team_admin` automatically + +#### Team Roles + +- **Team Admin**: Full control over team settings and management +- **Team User**: Basic team member (for future expansion) + +#### Team Permissions + +| Permission | Description | +|------------|-------------| +| `teams.create` | Create new teams (up to limit) | +| `teams.view` | View team details | +| `teams.edit` | Edit team settings | +| `teams.delete` | Delete team | +| `teams.manage` | Full team management | +| `team.members.view` | View team members | +| `team.members.manage` | Manage team member roles | + +### Team API Endpoints + +#### Get User's Teams + +```http +GET /api/users/me/teams +Authorization: Required (authenticated user) +``` + +#### Create Team + +```http +POST /api/teams +Authorization: Required (teams.create permission) +Content-Type: application/json + +{ + "name": "My New Team", + "description": "Team description" +} +``` + +#### Get Team by ID + +```http +GET /api/teams/:id +Authorization: Required (teams.view permission) +``` + +#### Update Team + +```http +PUT /api/teams/:id +Authorization: Required (teams.edit permission) +Content-Type: application/json + +{ + "name": "Updated Team Name", + "description": "Updated description" +} +``` + +#### Delete Team + +```http +DELETE /api/teams/:id +Authorization: Required (teams.delete permission) +``` + +#### Get Team Members + +```http +GET /api/teams/:id/members +Authorization: Required (team.members.view permission) +``` + +### Team Service Methods + +The `TeamService` class provides comprehensive team management: + +```typescript +// Create team +const team = await TeamService.createTeam({ + name: 'My Team', + owner_id: userId, + description: 'Team description' +}); + +// Get user's teams +const teams = await TeamService.getUserTeams(userId); + +// Check team limits +const canCreate = await TeamService.canUserCreateTeam(userId); + +// Team membership checks +const isAdmin = await TeamService.isTeamAdmin(teamId, userId); +const isOwner = await TeamService.isTeamOwner(teamId, userId); +``` + +## Database Schema + +### Roles Table + +```sql +CREATE TABLE roles ( + id TEXT PRIMARY KEY, -- Role identifier (e.g., 'global_admin') + name TEXT NOT NULL UNIQUE, -- Display name (e.g., 'Global Administrator') + description TEXT, -- Role description + permissions TEXT NOT NULL, -- JSON array of permissions + is_system_role BOOLEAN DEFAULT FALSE, -- Prevents deletion of core roles + created_at INTEGER NOT NULL, -- Creation timestamp + updated_at INTEGER NOT NULL -- Last update timestamp +); +``` + +### User Role Assignment + +The `authUser` table includes a `role_id` column that references the `roles` table: + +```sql +ALTER TABLE authUser ADD COLUMN role_id TEXT DEFAULT 'global_user' REFERENCES roles(id); +``` + +## API Endpoints + +### Role Management + +#### List Roles + +```http +GET /api/roles +Authorization: Required (roles.manage permission) +``` + +**Response:** + +```json +{ + "success": true, + "data": [ + { + "id": "global_admin", + "name": "Global Administrator", + "description": "Full system access with user management capabilities", + "permissions": ["users.list", "users.view", "users.edit", "users.delete", "users.create", "roles.manage", "system.admin"], + "is_system_role": true, + "created_at": "2025-01-30T15:00:00.000Z", + "updated_at": "2025-01-30T15:00:00.000Z" + } + ] +} +``` + +#### Get Role by ID + +```http +GET /api/roles/:id +Authorization: Required (roles.manage permission) +``` + +#### Create Role + +```http +POST /api/roles +Authorization: Required (roles.manage permission) +Content-Type: application/json + +{ + "id": "moderator", + "name": "Moderator", + "description": "Content moderation capabilities", + "permissions": ["users.view", "content.moderate"] +} +``` + +#### Update Role + +```http +PUT /api/roles/:id +Authorization: Required (roles.manage permission) +Content-Type: application/json + +{ + "name": "Updated Role Name", + "description": "Updated description", + "permissions": ["updated.permission"] +} +``` + +**Note:** System roles (`is_system_role: true`) cannot be updated or deleted. + +#### Delete Role + +```http +DELETE /api/roles/:id +Authorization: Required (roles.manage permission) +``` + +**Restrictions:** + +- Cannot delete system roles +- Cannot delete roles that are assigned to users + +#### Get Available Permissions + +```http +GET /api/roles/permissions +Authorization: Required (roles.manage permission) +``` + +### User Management + +#### List Users + +```http +GET /api/users +Authorization: Required (users.list permission) +``` + +#### Get User by ID + +```http +GET /api/users/:id +Authorization: Required (own profile or system.admin permission) +``` + +#### Update User + +```http +PUT /api/users/:id +Authorization: Required (own profile or system.admin permission) +Content-Type: application/json + +{ + "username": "newusername", + "email": "newemail@example.com", + "first_name": "John", + "last_name": "Doe", + "role_id": "global_user" +} +``` + +**Restrictions:** + +- Users cannot change their own role (only admins can) +- Email and username must be unique + +#### Delete User + +```http +DELETE /api/users/:id +Authorization: Required (users.delete permission) +``` + +**Restrictions:** + +- Cannot delete your own account +- Cannot delete the last global administrator + +#### Assign Role to User + +```http +PUT /api/users/:id/role +Authorization: Required (users.edit permission) +Content-Type: application/json + +{ + "role_id": "global_admin" +} +``` + +**Restrictions:** + +- Cannot change your own role + +#### Get Current User Profile + +```http +GET /api/users/me +Authorization: Required (authenticated user) +``` + +#### Get User Statistics + +```http +GET /api/users/stats +Authorization: Required (users.list permission) +``` + +#### Get Users by Role + +```http +GET /api/users/role/:roleId +Authorization: Required (users.list permission) +``` + +## Permission System + +### Available Permissions + +| Permission | Description | +|------------|-------------| +| `users.list` | List all users in the system | +| `users.view` | View detailed user information | +| `users.edit` | Edit user information and assign roles | +| `users.delete` | Delete user accounts | +| `users.create` | Create new user accounts | +| `roles.manage` | Create, update, and delete roles | +| `system.admin` | Administrative system access | +| `settings.view` | View global application settings | +| `settings.edit` | Create and update global application settings | +| `settings.delete` | Delete global application settings | +| `profile.view` | View own profile information | +| `profile.edit` | Edit own profile information | +| `teams.create` | Create new teams (up to limit) | +| `teams.view` | View team details | +| `teams.edit` | Edit team settings | +| `teams.delete` | Delete team | +| `teams.manage` | Full team management | +| `team.members.view` | View team members | +| `team.members.manage` | Manage team member roles | + +### Permission Checking + +The system provides several ways to check permissions: + +#### Middleware Functions + +```typescript +import { requirePermission, requireRole, requireGlobalAdmin } from '../middleware/roleMiddleware'; + +// Require specific permission +fastify.get('/admin-only', { + preHandler: requirePermission('system.admin') +}, handler); + +// Require specific role +fastify.get('/admin-role', { + preHandler: requireRole('global_admin') +}, handler); + +// Require global admin (shorthand) +fastify.get('/global-admin', { + preHandler: requireGlobalAdmin() +}, handler); +``` + +#### Utility Functions + +```typescript +import { checkUserPermission, getUserRole } from '../middleware/roleMiddleware'; + +// Check permission programmatically +const hasPermission = await checkUserPermission(userId, 'users.edit'); + +// Get user's role information +const userRole = await getUserRole(userId); +``` + +## User Registration Flow + +### First User + +When the first user registers in the system: + +1. They are automatically assigned the `global_admin` role +2. This ensures there's always at least one administrator + +### Subsequent Users + +All subsequent users are assigned the `global_user` role by default. + +### Registration Code Example + +```typescript +// Check if this is the first user +const allUsers = await db.select().from(authUserTable).limit(1); +const isFirstUser = allUsers.length === 0; +const defaultRole = isFirstUser ? 'global_admin' : 'global_user'; + +// Create user with appropriate role +await db.insert(authUserTable).values({ + // ... other user data + role_id: defaultRole +}); +``` + +## Security Considerations + +### Role Protection + +- **System Roles**: Cannot be modified or deleted +- **Last Admin Protection**: Cannot delete the last global administrator +- **Self-Role Protection**: Users cannot change their own roles +- **Self-Delete Protection**: Users cannot delete their own accounts + +### Permission Validation + +- All permissions are validated against a whitelist +- Invalid permissions are rejected during role creation/update +- Database constraints ensure referential integrity + +### Session Security + +- Role information is fetched fresh for each permission check +- No role caching to prevent stale permission issues +- Lucia v3 handles secure session management + +## Adding New Roles + +### 1. Define Permissions + +First, add any new permissions to the available permissions list: + +```typescript +// In services/backend/src/routes/roles/schemas.ts +export const AVAILABLE_PERMISSIONS = [ + // ... existing permissions + 'content.moderate', + 'reports.view', + 'analytics.access', +] as const; +``` + +### 2. Create Role via API + +Use the role creation API to add new roles: + +```http +POST /api/roles +{ + "id": "content_moderator", + "name": "Content Moderator", + "description": "Manages user-generated content", + "permissions": ["users.view", "content.moderate", "reports.view"] +} +``` + +### 3. Update Default Permissions (Optional) + +If you want to include the role in default setups: + +```typescript +// In services/backend/src/services/roleService.ts +static getDefaultPermissions() { + return { + global_admin: [/* ... */], + global_user: [/* ... */], + content_moderator: ['users.view', 'content.moderate', 'reports.view'], + }; +} +``` + +## Migration and Setup + +### Database Migration + +The role system is set up through migration `0003_huge_prism.sql` (generated using `npm run db:generate`): + +1. Creates the `roles` table +2. Adds `role_id` column to `authUser` table +3. Seeds default roles (`global_admin`, `global_user`) +4. Assigns existing users to `global_user` +5. Promotes the first user to `global_admin` + +### Manual Setup + +If you need to manually set up roles: + +```sql +-- Insert default roles +INSERT INTO roles (id, name, description, permissions, is_system_role, created_at, updated_at) VALUES +('global_admin', 'Global Administrator', 'Full system access', '["users.list","users.view","users.edit","users.delete","users.create","roles.manage","system.admin"]', 1, strftime('%s', 'now') * 1000, strftime('%s', 'now') * 1000), +('global_user', 'Global User', 'Standard user access', '["profile.view","profile.edit"]', 1, strftime('%s', 'now') * 1000, strftime('%s', 'now') * 1000); + +-- Assign roles to users +UPDATE authUser SET role_id = 'global_user' WHERE role_id IS NULL; +UPDATE authUser SET role_id = 'global_admin' WHERE id = (SELECT id FROM authUser ORDER BY id ASC LIMIT 1); +``` + +## Troubleshooting + +### Common Issues + +#### Permission Denied Errors + +- Verify the user has the required permission +- Check if the user's role includes the necessary permission +- Ensure the role exists and is properly assigned + +#### Role Assignment Failures + +- Verify the target role exists +- Check if you're trying to assign a role to yourself (not allowed) +- Ensure you have `users.edit` permission + +#### Migration Issues + +- Ensure the database is properly initialized +- Check that previous migrations have been applied +- Verify foreign key constraints are working + +### Debug Commands + +```typescript +// Check user's current role and permissions +const userRole = await roleService.getUserRole(userId); +console.log('User role:', userRole); + +// Check specific permission +const hasPermission = await roleService.userHasPermission(userId, 'users.edit'); +console.log('Has permission:', hasPermission); + +// List all roles +const allRoles = await roleService.getAllRoles(); +console.log('All roles:', allRoles); +``` + +## Future Enhancements + +### Planned Features + +- **Hierarchical Roles**: Parent-child role relationships +- **Temporary Permissions**: Time-limited access grants +- **Permission Groups**: Logical grouping of related permissions +- **Audit Logging**: Track role and permission changes +- **Role Templates**: Predefined role configurations + +### Extension Points + +The system is designed to be extensible: + +- Add new permissions by updating the `AVAILABLE_PERMISSIONS` array +- Create custom middleware for complex permission logic +- Implement role-based UI components in the frontend +- Add role-specific business logic in services + +## Best Practices + +### Role Design + +- Keep roles focused and specific +- Use descriptive names and descriptions +- Group related permissions logically +- Avoid overly broad permissions + +### Permission Naming + +- Use dot notation for hierarchy (`users.edit`, `content.moderate`) +- Be specific about the action (`view`, `edit`, `delete`, `create`) +- Use consistent naming patterns + +### Security + +- Always check permissions at the API level +- Don't rely solely on frontend permission checks +- Regularly audit role assignments +- Monitor for privilege escalation attempts + +### Performance + +- Permission checks are lightweight but avoid excessive calls +- Consider caching user roles for high-frequency operations +- Use middleware for route-level protection +- Batch permission checks when possible diff --git a/docs/deploystack/development/backend/security.mdx b/docs/deploystack/development/backend/security.mdx new file mode 100644 index 0000000..c4fca87 --- /dev/null +++ b/docs/deploystack/development/backend/security.mdx @@ -0,0 +1,97 @@ +--- +title: Security Policy +description: Comprehensive security guidelines covering password hashing, session management, encryption, and vulnerability reporting for DeployStack Backend. +--- + +# Security Policy + +This document outlines security procedures and policies for the backend service. + +## Reporting a Vulnerability + +If you discover a security vulnerability, please report it to us as soon as possible. We appreciate your efforts to disclose your findings responsibly. Please email us at [SECURITY_CONTACT_EMAIL_ADDRESS_HERE - *you'll need to replace this*] with a detailed description of the vulnerability and steps to reproduce it. + +We will acknowledge receipt of your vulnerability report promptly and work with you to understand and address the issue. We ask that you do not publicly disclose the vulnerability until we have had a chance to remediate it. + +## Password Hashing + +User passwords are never stored in plaintext. We employ a strong, adaptive hashing algorithm to protect user credentials. + +- **Algorithm:** We will use `argon2id`, which is a part of the Argon2 family of algorithms (Argon2id is generally recommended as it provides resistance against both side-channel attacks and GPU cracking attacks). +- **Salt Generation:** A unique, cryptographically secure salt is automatically generated for each user's password by the `argon2` library at the time of account creation or password change. This salt is then stored as part of the resulting hash string. +- **Parameters:** We use appropriate parameters for `argon2` (e.g., memory cost, time cost, and parallelism) to ensure that the hashing process is computationally intensive, making brute-force attacks significantly more difficult. These parameters are chosen to balance security with acceptable performance on our servers and may be adjusted based on hardware improvements over time. +- **Verification:** During login, the provided password and the stored salt (extracted from the hash string) are used to re-compute the hash. This newly computed hash is then compared against the stored hash in a constant-time manner (handled by the `argon2` library's verify function) to help prevent timing attacks. + +This approach ensures that even if the database were compromised, recovering the original passwords would be computationally infeasible. + +## Session Management + +User sessions are managed using `lucia-auth` v3. + +- Session identifiers are cryptographically random (40 characters) generated using Lucia's `generateId()` function and stored in secure, HTTP-only cookies to prevent XSS attacks from accessing them. +- Sessions have defined expiration times (30 days from creation) to limit the window of opportunity for session hijacking. +- Session data is stored in the `authSession` table with proper foreign key constraints to the `authUser` table. +- Session cookies are configured with appropriate security attributes: + - `httpOnly`: true (prevents JavaScript access) + - `secure`: true in production (HTTPS only) + - `sameSite`: 'lax' (CSRF protection) + +## Data Validation + +All incoming data from clients (e.g., API request bodies, URL parameters) is rigorously validated using `zod` schemas on the server-side before being processed. This helps prevent common vulnerabilities such as injection attacks and unexpected data handling errors. + +- Registration endpoint validates: username, email, password, first_name, last_name +- **Email verification endpoint validates: verification token format and expiration** +- Email addresses are normalized to lowercase before storage +- Duplicate username and email checks are performed before user creation +- **Email verification status is checked during login when verification is enabled** +- All database operations use parameterized queries via Drizzle ORM to prevent SQL injection + +## Email Verification + +Email verification is implemented to ensure account ownership and prevent unauthorized account creation. + +- **Verification Tokens:** Cryptographically secure tokens generated using `generateId(32)` (256-bit entropy) +- **Token Expiration:** Verification tokens expire after 24 hours to limit exposure window +- **Token Storage:** Tokens are stored hashed in the database using the same argon2 parameters as passwords +- **Secure Links:** Verification links use HTTPS in production and include the full token in query parameters +- **Token Validation:** Constant-time comparison used for token verification to prevent timing attacks +- **Single Use:** Tokens are invalidated immediately after successful verification +- **Account Security:** Unverified accounts cannot log in when email verification is enabled via `global.send_mail` setting +- **Global Administrator Exception:** The first registered user (global administrator) is automatically verified for system access +- **Database Schema Security:** `email_verified` boolean field with secure default (false) +- **Cleanup Mechanism:** Expired tokens are automatically cleaned up to prevent database bloat + +## Global Settings Encryption + +Sensitive global application settings (SMTP credentials, API keys, etc.) are encrypted at rest using industry-standard encryption. + +- **Algorithm:** AES-256-GCM (Galois/Counter Mode) +- **Key Derivation:** Scrypt with salt for key derivation from environment secret +- **Authenticated Encryption:** Prevents tampering with encrypted data +- **Unique Initialization Vectors:** Each encryption operation uses a unique IV +- **Environment-Based Key:** Encryption key derived from `DEPLOYSTACK_ENCRYPTION_SECRET` environment variable +- **Additional Authenticated Data (AAD):** Extra security layer to prevent data manipulation + +This approach ensures that sensitive configuration data remains secure even if the database is compromised. The encryption system is separate from password hashing to maintain proper separation of concerns. + +## Dependencies + +We strive to keep our dependencies up-to-date and regularly review them for known vulnerabilities. Automated tools may be used to scan for vulnerabilities in our dependency tree. + +### Key Security Dependencies + +- `@node-rs/argon2`: Password hashing +- `lucia`: Session management +- `drizzle-orm`: Database ORM with parameterized queries +- `zod`: Input validation and sanitization +- `@fastify/cookie`: Secure cookie handling +- `node:crypto`: Built-in cryptographic functions for global settings encryption + +## Infrastructure Security + +[Placeholder: Add details about infrastructure security, e.g., network configuration, firewalls, access controls, HTTPS enforcement, etc., as applicable to your deployment environment.] + +## Incident Response + +[Placeholder: Outline your incident response plan. Who to contact, steps to take, etc.] diff --git a/docs/deploystack/development/backend/test.mdx b/docs/deploystack/development/backend/test.mdx new file mode 100644 index 0000000..4f35e3a --- /dev/null +++ b/docs/deploystack/development/backend/test.mdx @@ -0,0 +1,150 @@ +--- +title: Backend End-to-End Testing +description: Complete E2E testing setup with Jest, Supertest, and automated database cleanup for DeployStack Backend development. +--- + +# Backend End-to-End Testing + +This document outlines the setup and execution of end-to-end (E2E) tests for the DeployStack backend. + +## Overview + +The E2E tests are designed to verify the functionality of the backend API endpoints, ensuring they behave as expected from an external perspective. This includes testing API responses, database interactions, and overall application flow. + +## Testing Framework and Libraries + +- **Jest**: A delightful JavaScript Testing Framework with a focus on simplicity. Used as the primary test runner and assertion library. +- **Supertest**: An HTTP assertion library that allows for easy testing of Node.js HTTP servers. Used to make requests to our Fastify backend and verify responses. +- **ts-jest**: A Jest transformer with source map support that lets you use Jest to test projects written in TypeScript. +- **fs-extra**: Used for file system operations needed during test setup (e.g., cleaning up database files). + +## Prerequisites + +Before running the tests, ensure you have installed all dependencies: + +```bash +# Navigate to the backend service directory +cd services/backend + +# Install dependencies (if you haven't already after recent changes) +npm install +``` + +## Test File Structure and Naming Convention + +- All E2E test files are located in the `services/backend/tests/` directory. +- Test files must follow the naming convention: `.e2e.test.ts`. +- Tests run sequentially in alphabetical order to ensure proper dependencies. + +### Current Test Files (in execution order) + +1. **`setup.e2e.test.ts`** - Database setup and initialization +2. **`user-registration.e2e.test.ts`** - User registration and role assignment +3. **`email-login.e2e.test.ts`** - Email login/logout and session management + +## Running Tests + +To execute the E2E test suite, run the following command from the `services/backend/` directory: + +```bash +npm run test:backend +``` + +Alternatively, you can run it from the root project directory: + +```bash +npm run test:backend +``` + +This command will: + +1. Trigger Jest to find and execute all `*.e2e.test.ts` files within the `services/backend/tests/` directory. +2. Execute a global setup script (`services/backend/tests/e2e/globalSetup.ts`) before any tests run. This script: + - Sets necessary environment variables for testing (e.g., `NODE_ENV=test`, a specific test port, a test encryption secret). + - Clears any existing test database files from `tests/e2e/test-data/` and `persistent_data/` directories to ensure a clean state. + - Programmatically starts the backend server on a dedicated test port. +3. Run the tests. +4. Execute a global teardown script (`services/backend/tests/globalTeardown.ts`) after all tests complete. This script stops the backend server. + +## Environment Variables for Testing + +The `globalSetup.ts` script automatically configures the following environment variables for the test run: + +- `NODE_ENV`: set to `test` +- `PORT`: set to a dedicated test port (e.g., 3002) +- `DEPLOYSTACK_ENCRYPTION_SECRET`: set to a dummy secret (`test-super-secret-key-for-jest`) + +## Writing New Tests + +When adding new E2E tests: + +1. Create a new file in `services/backend/tests/` following the `.e2e.test.ts` naming convention. +2. Import `request` from `supertest` and the `FastifyInstance` type if needed. +3. Access the globally available test server instance via `global.__TEST_SERVER__`. +4. Use `describe` and `it` blocks from Jest to structure your tests. +5. Use `supertest` to make requests to your API: + + ```typescript + import request from 'supertest'; + import { FastifyInstance } from 'fastify'; + + describe('GET /api/some-endpoint', () => { + let server: FastifyInstance; + + beforeAll(() => { + server = global.__TEST_SERVER__; + }); + + it('should return a 200 OK for a valid request', async () => { + const response = await request(server.server).get('/api/some-endpoint'); + expect(response.status).toBe(200); + // Add more assertions on response.body, headers, etc. + }); + }); + ``` + +6. Remember that `globalSetup.ts` cleans the database state before tests. If your tests rely on specific pre-existing data beyond the initial setup, you'll need to create that data within your test or a `beforeEach` block. + +## Current Test Suites + +### 1. `setup.e2e.test.ts` + +- **Purpose**: Verifies the initial database setup functionality. +- **Key Checks**: + - Ensures the test database file does not exist before setup. + - Calls `POST /api/db/setup` with `{"type": "sqlite"}`. + - Verifies the API response indicates successful setup initiation. + - Checks that the SQLite database file is created in the test data directory (`tests/e2e/test-data/deploystack.test.db`). + - Calls `GET /api/db/status` and verifies the response shows `configured: true`, `initialized: true`, and `dialect: "sqlite"`. + - Validates global settings initialization without errors. + - Confirms all migrations are applied successfully. + - Tests proper error handling for duplicate setup attempts. + +### 2. `user-registration.e2e.test.ts` + +- **Purpose**: Tests user registration functionality and role assignment logic. +- **Key Checks**: + - Registers the first user and verifies they receive `global_admin` role. + - Registers a second user and verifies they receive `global_user` role. + - Confirms both users exist in the database with correct roles. + - Validates that default teams are created for both users. + - Tests duplicate email and username prevention. + - Stores user IDs and session cookies for subsequent tests. + +### 3. `email-login.e2e.test.ts` + +- **Purpose**: Tests email-based authentication, session management, and logout functionality. +- **Key Checks**: + - Logs in both users with email and password. + - Verifies user sessions exist and work correctly. + - Tests invalid login attempts (wrong email/password). + - Logs out both users and confirms session invalidation. + - Verifies no active sessions remain after logout. + - Tests graceful handling of logout without valid session. + - Confirms users can re-login after logout. + +## Troubleshooting + +- **`Cannot find module 'supertest'` (or similar type errors)**: Ensure you have run `npm install` in the `services/backend` directory after the testing dependencies were added to `package.json`. +- **Port conflicts**: The tests run on a dedicated port (defaulted to 3002 in `globalSetup.ts`). Ensure this port is free. +- **Database state**: Tests are designed to run against a clean database. `globalSetup.ts` handles this. If you encounter issues related to database state, ensure no other processes are interfering with `services/backend/persistent_data/`. diff --git a/docs/deploystack/development/frontend/index.mdx b/docs/deploystack/development/frontend/index.mdx new file mode 100644 index 0000000..94e0694 --- /dev/null +++ b/docs/deploystack/development/frontend/index.mdx @@ -0,0 +1,388 @@ +--- +title: Frontend Development Guide +description: Complete guide to developing and contributing to the DeployStack frontend application built with Vue 3, TypeScript, and Vite. +--- + +# DeployStack Frontend Development + +The DeployStack frontend is a modern web application built with Vue 3, TypeScript, and Vite, specifically designed for managing MCP (Model Context Protocol) server deployments. This guide covers everything you need to know to develop and contribute to the frontend. + +## Technology Stack + +- **Framework**: Vue 3 with Composition API +- **Language**: TypeScript for type safety +- **Build Tool**: Vite for fast development and building +- **Styling**: TailwindCSS with shadcn-vue components +- **Icons**: Lucide Icons +- **Internationalization**: Vue I18n +- **State Management**: Pinia (when needed) +- **Routing**: Vue Router + +## Quick Start + +### Prerequisites + +- Node.js 18 or higher +- npm 8 or higher + +### Development Setup + +1. **Navigate to frontend directory**: + ```bash + cd services/frontend + ``` + +2. **Install dependencies**: + ```bash + npm install + ``` + +3. **Start development server**: + ```bash + npm run dev + ``` + +4. **Build for production**: + ```bash + npm run build + ``` + +The development server will start at `http://localhost:5173` with hot module replacement enabled. + +## Project Structure + +```bash +services/frontend/ +├── src/ +│ ├── components/ # Reusable Vue components +│ ├── views/ # Page-level components +│ ├── router/ # Vue Router configuration +│ ├── stores/ # Pinia stores (state management) +│ ├── services/ # API services and utilities +│ ├── plugins/ # Frontend plugin system +│ ├── i18n/ # Internationalization files +│ ├── utils/ # Utility functions +│ ├── types/ # TypeScript type definitions +│ └── assets/ # Static assets +├── public/ # Public static files +├── dist/ # Built application (generated) +└── ... +``` + +## Development Guidelines + +### Code Style + +- Use TypeScript for all new code +- Follow Vue 3 Composition API patterns +- Use ` + + +``` + +## UI Components and Styling + +### TailwindCSS Integration + +The frontend uses TailwindCSS for styling with the shadcn-vue component library for consistent UI elements. + +#### Installing New shadcn-vue Components + +```bash +npx shadcn-vue@latest add button +npx shadcn-vue@latest add input +npx shadcn-vue@latest add dialog +``` + +#### Custom Component Example + +```vue + +``` + +### Icons + +The project uses Lucide Icons through the `lucide-vue-next` package. + +#### Using Icons + +```vue + + + +``` + +## Environment Configuration + +The frontend supports environment variables for both development and production environments. + +### Development Environment + +Create a `.env` file in the `services/frontend` directory: + +```bash +VITE_API_URL=http://localhost:3000 +VITE_APP_TITLE=DeployStack (Development) +VITE_ENABLE_DEBUG=true +``` + +### Production Environment + +Environment variables can be passed to the Docker container: + +```bash +docker run -it -p 80:80 \ + -e VITE_API_URL="https://api.deploystack.io" \ + -e VITE_APP_TITLE="DeployStack" \ + -e VITE_ENABLE_DEBUG="false" \ + deploystack/frontend:latest +``` + +### Accessing Environment Variables + +Use the `getEnv` utility function for consistent access: + +```typescript +import { getEnv } from '@/utils/env' + +// In your components +const apiUrl = getEnv('VITE_API_URL') +const appTitle = getEnv('VITE_APP_TITLE') +const debugMode = getEnv('VITE_ENABLE_DEBUG') === 'true' +``` + +### Adding New Environment Variables + +1. **Add type definitions** in `env.d.ts`: + +```typescript +interface ImportMetaEnv { + readonly VITE_API_URL: string + readonly VITE_APP_TITLE: string + readonly VITE_ENABLE_DEBUG: string + readonly VITE_NEW_VARIABLE: string +} + +interface Window { + RUNTIME_ENV?: { + VITE_API_URL?: string + VITE_APP_TITLE?: string + VITE_ENABLE_DEBUG?: string + VITE_NEW_VARIABLE?: string + // Non-VITE variables + CUSTOM_VAR?: string + } +} +``` + +2. **For non-VITE variables** in Docker, update `env-config.sh`: + +```bash +# Add specific non-VITE_ variables you want to expose +for var in CUSTOM_VAR OTHER_VAR; do + # Script logic here +done +``` + +## API Integration + +### Service Layer Pattern + +The frontend uses a service layer pattern for API communication: + +```typescript +// services/mcpServerService.ts +export class McpServerService { + private static baseUrl = getEnv('VITE_API_URL') + + static async getAllServers(): Promise { + const response = await fetch(`${this.baseUrl}/api/mcp-servers`) + if (!response.ok) { + throw new Error('Failed to fetch MCP servers') + } + return response.json() + } + + static async deployServer(serverId: string, config: DeployConfig): Promise { + const response = await fetch(`${this.baseUrl}/api/mcp-servers/${serverId}/deploy`, { + method: 'POST', + headers: { + 'Content-Type': 'application/json', + }, + body: JSON.stringify(config), + }) + + if (!response.ok) { + throw new Error('Failed to deploy MCP server') + } + + return response.json() + } +} +``` + +### Using Services in Components + +```vue + +``` + +## Next Steps + +Continue reading the detailed guides: + +- [Internationalization (i18n)](/deploystack/development/frontend/internationalization) - Multi-language support +- [Plugin System](/deploystack/development/frontend/plugins) - Extending functionality +- [Router Optimization](/deploystack/development/frontend/router-optimization) - Performance improvements +- [Contributing Guidelines](/deploystack/development/frontend/contributing) - How to contribute + +## Docker Development + +### Building the Frontend + +```bash +# Build the Docker image +docker build -t deploystack/frontend:dev . + +# Run with development configuration +docker run -it -p 8080:80 \ + -e VITE_API_URL="http://localhost:3000" \ + -e VITE_APP_TITLE="DeployStack (Docker Dev)" \ + deploystack/frontend:dev +``` + +### Production Deployment + +The frontend is designed to work seamlessly with the backend service: + +```bash +# Production deployment +docker run -d -p 8080:80 \ + -e VITE_API_URL="https://api.your-domain.com" \ + -e VITE_APP_TITLE="DeployStack" \ + deploystack/frontend:latest +``` + +## Troubleshooting + +### Common Issues + +1. **Build failures**: Check Node.js and npm versions +2. **API connection issues**: Verify `VITE_API_URL` environment variable +3. **Styling issues**: Ensure TailwindCSS is properly configured +4. **TypeScript errors**: Run `npm run lint` to check for issues + +### Development Tips + +- Use Vue DevTools browser extension for debugging +- Enable TypeScript strict mode in `tsconfig.json` +- Use ESLint and Prettier for code consistency +- Test components in isolation when possible diff --git a/docs/deploystack/development/frontend/internationalization.mdx b/docs/deploystack/development/frontend/internationalization.mdx new file mode 100644 index 0000000..2ba4c55 --- /dev/null +++ b/docs/deploystack/development/frontend/internationalization.mdx @@ -0,0 +1,882 @@ +--- +title: Internationalization (i18n) +description: Guide to implementing multi-language support in DeployStack frontend using Vue I18n with modular file structure. +--- + +# Internationalization (i18n) + +DeployStack supports multiple languages through Vue I18n with a modular file structure that organizes translations by feature. This approach makes it easy to maintain translations and add new languages. + +## Architecture Overview + +The i18n system is designed with modularity and maintainability in mind: + +- **Feature-based organization**: Translations are grouped by application features +- **Modular structure**: Each feature has its own translation file +- **Scalable approach**: Easy to add new languages and features +- **Type safety**: TypeScript support for translation keys + +## Directory Structure + +```bash +src/i18n/ +├── index.ts # Main i18n initialization +└── locales/ + ├── en/ # English translations + │ ├── index.ts # Exports all English translations + │ ├── common.ts # Common translations (buttons, labels, etc.) + │ ├── login.ts # Login page specific translations + │ ├── register.ts # Register page specific translations + │ ├── dashboard.ts # Dashboard specific translations + │ ├── mcp-servers.ts # MCP server management translations + │ └── deployment.ts # Deployment related translations + └── de/ # German translations (example) + ├── index.ts + ├── common.ts + └── ... +``` + +## Setting Up i18n + +### Main Configuration + +The main i18n configuration in `src/i18n/index.ts`: + +```typescript +import { createI18n } from 'vue-i18n' +import en from './locales/en' +import de from './locales/de' // Example additional language + +const i18n = createI18n({ + legacy: false, // Use Composition API + locale: 'en', // Default language + fallbackLocale: 'en', // Fallback language + messages: { + en, + de + } +}) + +export default i18n +``` + +### Locale Index File + +Each locale has an index file that exports all translations: + +```typescript +// src/i18n/locales/en/index.ts +import common from './common' +import login from './login' +import register from './register' +import dashboard from './dashboard' +import mcpServers from './mcp-servers' +import deployment from './deployment' + +export default { + common, + login, + register, + dashboard, + mcpServers, + deployment +} +``` + +## Creating Translation Files + +### Common Translations + +File: `src/i18n/locales/en/common.ts` + +```typescript +export default { + // Navigation + navigation: { + dashboard: 'Dashboard', + mcpServers: 'MCP Servers', + deployments: 'Deployments', + settings: 'Settings', + logout: 'Logout' + }, + + // Common buttons and actions + buttons: { + save: 'Save', + cancel: 'Cancel', + delete: 'Delete', + edit: 'Edit', + create: 'Create', + deploy: 'Deploy', + stop: 'Stop', + restart: 'Restart', + view: 'View', + download: 'Download' + }, + + // Status indicators + status: { + running: 'Running', + stopped: 'Stopped', + error: 'Error', + pending: 'Pending', + deploying: 'Deploying', + healthy: 'Healthy', + unhealthy: 'Unhealthy' + }, + + // Common labels + labels: { + name: 'Name', + description: 'Description', + status: 'Status', + created: 'Created', + updated: 'Updated', + version: 'Version', + author: 'Author', + email: 'Email', + password: 'Password' + }, + + // Validation messages + validation: { + required: 'This field is required', + email: 'Please enter a valid email address', + minLength: 'Must be at least {min} characters', + maxLength: 'Must be no more than {max} characters', + passwordMismatch: 'Passwords do not match' + }, + + // Common messages + messages: { + loading: 'Loading...', + saving: 'Saving...', + saved: 'Saved successfully', + error: 'An error occurred', + noData: 'No data available', + confirmDelete: 'Are you sure you want to delete this item?' + } +} +``` + +### Feature-Specific Translations + +File: `src/i18n/locales/en/mcp-servers.ts` + +```typescript +export default { + title: 'MCP Servers', + subtitle: 'Manage your Model Context Protocol servers', + + catalog: { + title: 'MCP Server Catalog', + description: 'Browse and deploy MCP servers from our community catalog', + search: 'Search servers...', + categories: { + all: 'All Categories', + databases: 'Databases', + apis: 'APIs', + tools: 'Development Tools', + productivity: 'Productivity', + integrations: 'Integrations' + } + }, + + deployment: { + title: 'Deploy MCP Server', + selectProvider: 'Select Cloud Provider', + configure: 'Configure Deployment', + credentials: { + title: 'Credentials', + description: 'Configure API keys and authentication', + addCredential: 'Add Credential', + apiKey: 'API Key', + secretKey: 'Secret Key', + token: 'Access Token' + }, + environment: { + title: 'Environment Variables', + description: 'Configure environment variables for your MCP server', + addVariable: 'Add Variable', + key: 'Variable Name', + value: 'Variable Value' + } + }, + + management: { + myServers: 'My Deployed Servers', + serverDetails: 'Server Details', + logs: 'View Logs', + metrics: 'Performance Metrics', + scale: 'Scale Server', + instances: 'Instances', + uptime: 'Uptime', + lastDeployed: 'Last Deployed' + }, + + forms: { + serverName: { + label: 'Server Name', + placeholder: 'Enter a name for your server deployment', + description: 'This will be used to identify your deployment' + }, + region: { + label: 'Deployment Region', + placeholder: 'Select region', + description: 'Choose the region closest to your users' + } + }, + + actions: { + deployNow: 'Deploy Now', + viewInCatalog: 'View in Catalog', + manageServer: 'Manage Server', + viewLogs: 'View Logs', + stopServer: 'Stop Server', + restartServer: 'Restart Server', + deleteDeployment: 'Delete Deployment' + }, + + notifications: { + deploymentStarted: 'Deployment started successfully', + deploymentCompleted: 'Server deployed successfully', + deploymentFailed: 'Deployment failed: {error}', + serverStopped: 'Server stopped successfully', + serverRestarted: 'Server restarted successfully', + serverDeleted: 'Server deployment deleted' + } +} +``` + +## Using Translations in Components + +### Basic Usage + +```vue + + + +``` + +### Advanced Usage with Computed Properties + +```vue + + + +``` + +### Form Validation with i18n + +```vue + + + +``` + +## Adding New Languages + +### 1. Create Language Directory + +```bash +mkdir -p src/i18n/locales/de +``` + +### 2. Create Translation Files + +Start with the common translations: + +```typescript +// src/i18n/locales/de/common.ts +export default { + navigation: { + dashboard: 'Dashboard', + mcpServers: 'MCP Server', + deployments: 'Bereitstellungen', + settings: 'Einstellungen', + logout: 'Abmelden' + }, + + buttons: { + save: 'Speichern', + cancel: 'Abbrechen', + delete: 'Löschen', + edit: 'Bearbeiten', + create: 'Erstellen', + deploy: 'Bereitstellen', + stop: 'Stoppen', + restart: 'Neu starten', + view: 'Anzeigen', + download: 'Herunterladen' + }, + + // ... continue with other translations +} +``` + +### 3. Create Locale Index + +```typescript +// src/i18n/locales/de/index.ts +import common from './common' +import login from './login' +import register from './register' +// ... import other feature translations + +export default { + common, + login, + register, + // ... export other translations +} +``` + +### 4. Update Main i18n Configuration + +```typescript +// src/i18n/index.ts +import en from './locales/en' +import de from './locales/de' + +const i18n = createI18n({ + legacy: false, + locale: 'en', + fallbackLocale: 'en', + messages: { + en, + de // Add the new language + } +}) +``` + +## Language Switching + +### Language Selector Component + +```vue + + + +``` + +## Best Practices + +### 1. Translation Key Naming + +Use descriptive, hierarchical naming: + +```typescript +// Good +'mcpServers.deployment.credentials.title' +'common.validation.passwordTooShort' +'dashboard.widgets.serverStatus.healthy' + +// Avoid +'title' +'error1' +'msg' +``` + +### 2. Parameterized Messages + +Use parameters for dynamic content: + +```typescript +// Translation file +export default { + messages: { + welcomeUser: 'Welcome back, {userName}!', + itemsCount: 'You have {count} {count, plural, one {item} other {items}}', + deploymentTime: 'Deployed {timeAgo} ago' + } +} + +// Usage +t('messages.welcomeUser', { userName: 'John' }) +t('messages.itemsCount', { count: 5 }) +``` + +### 3. Context-Aware Translations + +Group related translations together: + +```typescript +export default { + serverStatus: { + running: { + label: 'Running', + description: 'Server is operating normally', + action: 'Stop Server' + }, + stopped: { + label: 'Stopped', + description: 'Server is not running', + action: 'Start Server' + } + } +} +``` + +### 4. Handle Missing Translations + +Always provide fallback values: + +```vue + +``` + +## TypeScript Integration + +### Translation Key Types + +Create type definitions for better IDE support: + +```typescript +// types/i18n.ts +export interface I18nMessages { + common: { + buttons: { + save: string + cancel: string + // ... other button translations + } + // ... other common translations + } + mcpServers: { + title: string + deployment: { + title: string + // ... other deployment translations + } + // ... other MCP server translations + } +} + +// Extend the vue-i18n module +declare module 'vue-i18n' { + export interface DefineLocaleMessage extends I18nMessages {} +} +``` + +### Typed Translation Function + +```typescript +import { useI18n } from 'vue-i18n' +import type { I18nMessages } from '@/types/i18n' + +// Create a typed version of the translation function +export function useTypedI18n() { + const { t, ...rest } = useI18n() + return { t, ...rest } +} +``` + +## Testing Translations + +### Testing Translation Keys + +```typescript +// tests/i18n.test.ts +import { describe, it, expect } from 'vitest' +import en from '@/i18n/locales/en' + +describe('i18n translations', () => { + it('should have all required common translations', () => { + expect(en.common.buttons.save).toBeDefined() + expect(en.common.buttons.cancel).toBeDefined() + expect(en.common.validation.required).toBeDefined() + }) + + it('should have MCP server translations', () => { + expect(en.mcpServers.title).toBeDefined() + expect(en.mcpServers.deployment.title).toBeDefined() + }) +}) +``` + +### Component Translation Testing + +```typescript +// tests/components/LanguageSelector.test.ts +import { mount } from '@vue/test-utils' +import { createI18n } from 'vue-i18n' +import LanguageSelector from '@/components/LanguageSelector.vue' + +const i18n = createI18n({ + legacy: false, + locale: 'en', + messages: { + en: { test: 'Test' }, + de: { test: 'Test' } + } +}) + +describe('LanguageSelector', () => { + it('should change language when selected', async () => { + const wrapper = mount(LanguageSelector, { + global: { + plugins: [i18n] + } + }) + + const select = wrapper.find('select') + await select.setValue('de') + + expect(i18n.global.locale.value).toBe('de') + }) +}) +``` + +## Performance Considerations + +### Lazy Loading Translations + +For large applications, consider lazy loading translation files: + +```typescript +// src/i18n/index.ts +import { createI18n } from 'vue-i18n' + +const i18n = createI18n({ + legacy: false, + locale: 'en', + fallbackLocale: 'en', + messages: {} +}) + +// Lazy load function +async function loadLocaleMessages(locale: string) { + if (i18n.global.availableLocales.includes(locale)) { + return + } + + try { + const messages = await import(`./locales/${locale}/index.ts`) + i18n.global.setLocaleMessage(locale, messages.default) + } catch (error) { + console.error(`Failed to load locale ${locale}:`, error) + } +} + +// Usage in components +export async function setLanguage(locale: string) { + await loadLocaleMessages(locale) + i18n.global.locale.value = locale +} +``` + +### Translation Caching + +Implement caching for frequently used translations: + +```typescript +// utils/translationCache.ts +const cache = new Map() + +export function getCachedTranslation(key: string, params?: any): string | null { + const cacheKey = `${key}-${JSON.stringify(params || {})}` + return cache.get(cacheKey) || null +} + +export function setCachedTranslation(key: string, params: any, value: string): void { + const cacheKey = `${key}-${JSON.stringify(params || {})}` + cache.set(cacheKey, value) +} +``` + +## Common Patterns + +### Form Validation Messages + +```typescript +// i18n/locales/en/validation.ts +export default { + serverName: { + required: 'Server name is required', + minLength: 'Server name must be at least 3 characters', + maxLength: 'Server name cannot exceed 50 characters', + invalidChars: 'Server name can only contain letters, numbers, and hyphens' + }, + deployment: { + region: { + required: 'Please select a deployment region', + invalid: 'Selected region is not available' + }, + credentials: { + apiKey: { + required: 'API key is required', + invalid: 'Invalid API key format' + } + } + } +} +``` + +### Status and Notification Messages + +```typescript +// i18n/locales/en/notifications.ts +export default { + success: { + serverDeployed: 'MCP server deployed successfully', + configurationSaved: 'Configuration saved', + credentialsUpdated: 'Credentials updated securely' + }, + error: { + deploymentFailed: 'Deployment failed: {reason}', + networkError: 'Network connection error. Please try again.', + unauthorized: 'You are not authorized to perform this action', + serverNotFound: 'Server not found or has been deleted' + }, + warning: { + unsavedChanges: 'You have unsaved changes. Are you sure you want to leave?', + serverRestarting: 'Server is restarting. This may take a few minutes.', + quotaExceeded: 'You have reached your deployment quota' + } +} +``` + +### Navigation and Menu Items + +```typescript +// i18n/locales/en/navigation.ts +export default { + main: { + dashboard: 'Dashboard', + catalog: 'MCP Catalog', + deployments: 'My Deployments', + teams: 'Teams', + settings: 'Settings' + }, + breadcrumbs: { + home: 'Home', + mcpServers: 'MCP Servers', + deployment: 'Deployment', + configuration: 'Configuration' + }, + actions: { + deploy: 'Deploy Server', + configure: 'Configure', + manage: 'Manage', + monitor: 'Monitor', + scale: 'Scale' + } +} +``` + +## Internationalization Checklist + +### Before Adding New Features + +- [ ] Plan translation structure for new components +- [ ] Identify reusable common translations +- [ ] Consider context and parameterization needs +- [ ] Plan for pluralization if needed + +### During Development + +- [ ] Use translation keys instead of hardcoded text +- [ ] Add proper TypeScript types for new translations +- [ ] Test with different languages if available +- [ ] Consider text length variations between languages + +### Before Release + +- [ ] Ensure all user-facing text is translatable +- [ ] Test language switching functionality +- [ ] Verify fallback translations work +- [ ] Check for missing translation keys +- [ ] Test form validation messages in different languages + +## Maintenance + +### Regular Translation Updates + +1. **Review translation completeness** for each supported language +2. **Update outdated translations** when features change +3. **Add missing translations** for new features +4. **Remove unused translation keys** to keep files clean + +### Translation File Organization + +Keep translation files organized and maintainable: + +```bash +# Good organization +src/i18n/locales/en/ +├── common.ts # Shared across app +├── navigation.ts # Navigation items +├── validation.ts # Form validation +├── notifications.ts # Success/error messages +├── features/ +│ ├── mcp-servers.ts +│ ├── deployment.ts +│ └── dashboard.ts +``` + +### Version Control Best Practices + +- Keep translation files in version control +- Use meaningful commit messages for translation changes +- Consider separate PRs for translation updates +- Document translation conventions in your project + +This comprehensive i18n setup ensures your DeployStack frontend can grow to support multiple languages while maintaining clean, organized, and maintainable translation files. diff --git a/docs/deploystack/development/frontend/meta.json b/docs/deploystack/development/frontend/meta.json new file mode 100644 index 0000000..adb4651 --- /dev/null +++ b/docs/deploystack/development/frontend/meta.json @@ -0,0 +1,4 @@ +{ + "title": "Frontend Development", + "description": "Complete guide to developing the DeployStack frontend application" +} diff --git a/docs/deploystack/development/frontend/plugins.mdx b/docs/deploystack/development/frontend/plugins.mdx new file mode 100644 index 0000000..ae5891a --- /dev/null +++ b/docs/deploystack/development/frontend/plugins.mdx @@ -0,0 +1,1299 @@ +--- +title: Plugin System +description: Complete guide to the DeployStack frontend plugin architecture for extending functionality with custom components, routes, and state management. +--- + +# Frontend Plugin System + +DeployStack's frontend features a powerful plugin architecture that enables extending the application with additional functionality, UI components, routes, and state management. This modular approach allows for clean separation of concerns and extensible development. + +## Architecture Overview + +The plugin system is designed with flexibility and maintainability in mind: + +- **Modular Extension**: Add new UI components at designated extension points +- **Route Registration**: Register new routes in the Vue Router +- **State Management**: Add new Pinia stores for plugin-specific state +- **Lifecycle Management**: Initialize and cleanup plugins properly +- **Type Safety**: Full TypeScript support for plugin development + +## Plugin Structure + +A standard plugin follows this directory structure: + +```bash +your-plugin/ +├── index.ts # Main plugin entry point (required) +├── components/ # Plugin-specific components +│ ├── PluginComponent.vue +│ └── PluginCard.vue +├── views/ # Plugin-specific views/pages +│ ├── PluginPage.vue +│ └── PluginSettings.vue +├── store.ts # Plugin-specific Pinia store (optional) +├── composables/ # Plugin-specific composables (optional) +│ └── usePluginFeature.ts +├── types.ts # Plugin-specific types (optional) +└── README.md # Plugin documentation +``` + +## Plugin Interface + +Every plugin must implement the `Plugin` interface: + +```typescript +interface Plugin { + meta: PluginMeta + initialize(app: App, router: Router, pinia: Pinia, pluginManager?: PluginManager): Promise + cleanup(): Promise +} + +interface PluginMeta { + id: string // Unique plugin identifier + name: string // Human-readable plugin name + version: string // Plugin version (semver) + description: string // Plugin description + author: string // Plugin author + dependencies?: string[] // Other plugin IDs this plugin depends on +} +``` + +## Creating Your First Plugin + +### 1. Basic Plugin Structure + +Create a new directory for your plugin: + +```bash +mkdir -p src/plugins/mcp-metrics-plugin +cd src/plugins/mcp-metrics-plugin +``` + +### 2. Create a Component + +Start with a simple Vue component: + +```vue + + + + +``` + +### 3. Implement the Plugin + +Create the main plugin file: + +```typescript +// src/plugins/mcp-metrics-plugin/index.ts +import type { Plugin } from '@/plugin-system/types' +import type { App } from 'vue' +import type { Router } from 'vue-router' +import type { Pinia } from 'pinia' +import { registerExtensionPoint } from '@/plugin-system/extension-points' +import MetricsWidget from './components/MetricsWidget.vue' +import MetricsPage from './views/MetricsPage.vue' + +class McpMetricsPlugin implements Plugin { + meta = { + id: 'mcp-metrics-plugin', + name: 'MCP Metrics Plugin', + version: '1.0.0', + description: 'Provides comprehensive metrics and analytics for MCP server deployments', + author: 'DeployStack Team' + } + + async initialize(app: App, router: Router, pinia: Pinia) { + console.log('Initializing MCP Metrics Plugin...') + + // Register the metrics widget in the dashboard + registerExtensionPoint('dashboard-widgets', MetricsWidget, this.meta.id, { + order: 10, // Show early in the dashboard + props: { + refreshInterval: 30000 // Refresh every 30 seconds + } + }) + + // Register a dedicated metrics page + router.addRoute({ + path: '/metrics', + name: 'Metrics', + component: MetricsPage, + meta: { + title: 'MCP Metrics', + requiresAuth: true + } + }) + + // Add navigation item (if supported by your app) + registerExtensionPoint('main-navigation', { + template: ` + + + Metrics + + `, + components: { BarChart: () => import('lucide-vue-next').then(m => m.BarChart) } + }, this.meta.id) + + console.log('MCP Metrics Plugin initialized successfully') + } + + async cleanup() { + console.log('Cleaning up MCP Metrics Plugin...') + // Perform any necessary cleanup + // Extension points are automatically cleaned up by the plugin manager + } +} + +export default McpMetricsPlugin +``` + +### 4. Create a Dedicated Page + +Create a full page view for your plugin: + +```vue + + + + +``` + +### 5. Add Plugin State Management + +Create a Pinia store for your plugin: + +```typescript +// src/plugins/mcp-metrics-plugin/store.ts +import { defineStore } from 'pinia' +import { ref, computed } from 'vue' + +export interface MetricsData { + totalServers: number + activeDeployments: number + totalRequests: number + responseTime: string + uptime: string + errorRate: string + throughput: string +} + +export interface ChartDataPoint { + hour: number + requests: number + errors: number +} + +export const useMetricsStore = defineStore('mcp-metrics', () => { + // State + const metrics = ref({ + totalServers: 0, + activeDeployments: 0, + totalRequests: 0, + responseTime: '0ms', + uptime: '0%', + errorRate: '0%', + throughput: '0 req/min' + }) + + const chartData = ref([]) + const isLoading = ref(false) + const lastUpdated = ref(null) + + // Getters + const healthScore = computed(() => { + const uptimePercent = parseFloat(metrics.value.uptime.replace('%', '')) + const errorPercent = parseFloat(metrics.value.errorRate.replace('%', '')) + return Math.max(0, 100 - errorPercent * 10) * (uptimePercent / 100) + }) + + const isHealthy = computed(() => healthScore.value > 80) + + // Actions + async function fetchMetrics() { + isLoading.value = true + try { + // Simulate API call + await new Promise(resolve => setTimeout(resolve, 1000)) + + metrics.value = { + totalServers: Math.floor(Math.random() * 20) + 10, + activeDeployments: Math.floor(Math.random() * 15) + 5, + totalRequests: Math.floor(Math.random() * 5000) + 1000, + responseTime: `${Math.floor(Math.random() * 200) + 50}ms`, + uptime: `${(99 + Math.random()).toFixed(1)}%`, + errorRate: `${(Math.random() * 2).toFixed(1)}%`, + throughput: `${(Math.random() * 2 + 0.5).toFixed(1)}k req/min` + } + + lastUpdated.value = new Date() + } catch (error) { + console.error('Failed to fetch metrics:', error) + throw error + } finally { + isLoading.value = false + } + } + + async function fetchChartData() { + try { + // Simulate API call for chart data + await new Promise(resolve => setTimeout(resolve, 800)) + + chartData.value = Array.from({ length: 24 }, (_, i) => ({ + hour: i, + requests: Math.floor(Math.random() * 100) + 50, + errors: Math.floor(Math.random() * 5) + })) + } catch (error) { + console.error('Failed to fetch chart data:', error) + throw error + } + } + + function refreshAllData() { + return Promise.all([ + fetchMetrics(), + fetchChartData() + ]) + } + + return { + // State + metrics, + chartData, + isLoading, + lastUpdated, + + // Getters + healthScore, + isHealthy, + + // Actions + fetchMetrics, + fetchChartData, + refreshAllData + } +}) +``` + +## Extension Points + +Extension points are designated areas in your application where plugins can inject components. + +### Using Extension Points in Your App + +Add extension points to your main application components: + +```vue + + +``` + +### Registering Components at Extension Points + +In your plugin's initialize method: + +```typescript +// Register a single component +registerExtensionPoint( + 'dashboard-widgets', // Extension point ID + MetricsWidget, // Vue component + this.meta.id, // Plugin ID + { + order: 10, // Display order (optional) + props: { // Props to pass to component (optional) + refreshInterval: 30000 + } + } +) + +// Register multiple components +registerExtensionPoint('action-buttons', RefreshButton, this.meta.id, { order: 1 }) +registerExtensionPoint('action-buttons', ExportButton, this.meta.id, { order: 2 }) +``` + +### Conditional Rendering + +Show specific plugin components based on conditions: + +```vue + +``` + +## Advanced Plugin Features + +### Plugin Dependencies + +Specify dependencies in your plugin metadata: + +```typescript +class AdvancedPlugin implements Plugin { + meta = { + id: 'advanced-plugin', + name: 'Advanced Plugin', + version: '1.0.0', + description: 'Advanced functionality that requires metrics plugin', + author: 'You', + dependencies: ['mcp-metrics-plugin'] // Require metrics plugin + } + + async initialize(app: App, router: Router, pinia: Pinia, pluginManager?: PluginManager) { + // Check if required plugins are available + const metricsPlugin = pluginManager?.getPlugin('mcp-metrics-plugin') + if (!metricsPlugin) { + throw new Error('MCP Metrics Plugin is required but not available') + } + + // Use functionality from the metrics plugin + console.log('Metrics plugin available:', metricsPlugin.meta.name) + } +} +``` + +### Plugin Configuration + +Support configuration through the plugin manager: + +```typescript +interface PluginConfig { + refreshInterval?: number + enableNotifications?: boolean + theme?: 'light' | 'dark' +} + +class ConfigurablePlugin implements Plugin { + private config: PluginConfig = {} + + async initialize(app: App, router: Router, pinia: Pinia, pluginManager?: PluginManager) { + // Get plugin configuration + this.config = pluginManager?.getPluginConfig(this.meta.id) || {} + + // Use configuration + const refreshInterval = this.config.refreshInterval || 30000 + const enableNotifications = this.config.enableNotifications !== false + + console.log('Plugin config:', this.config) + } +} +``` + +### Inter-Plugin Communication + +Plugins can communicate through events or shared stores: + +```typescript +// Event-based communication +class PublisherPlugin implements Plugin { + async initialize(app: App) { + // Emit events + app.config.globalProperties.$pluginEventBus.emit('metrics-updated', data) + } +} + +class SubscriberPlugin implements Plugin { + async initialize(app: App) { + // Listen to events + app.config.globalProperties.$pluginEventBus.on('metrics-updated', (data) => { + console.log('Received metrics update:', data) + }) + } +} +``` + +### Plugin Composables + +Create reusable composition functions: + +```typescript +// src/plugins/mcp-metrics-plugin/composables/useMetrics.ts +import { ref, onMounted, onUnmounted } from 'vue' +import { useMetricsStore } from '../store' + +export function useMetrics(refreshInterval = 30000) { + const store = useMetricsStore() + const isAutoRefreshEnabled = ref(true) + let intervalId: number | null = null + + function startAutoRefresh() { + if (intervalId) clearInterval(intervalId) + + intervalId = setInterval(() => { + if (isAutoRefreshEnabled.value) { + store.fetchMetrics() + } + }, refreshInterval) + } + + function stopAutoRefresh() { + if (intervalId) { + clearInterval(intervalId) + intervalId = null + } + } + + function toggleAutoRefresh() { + isAutoRefreshEnabled.value = !isAutoRefreshEnabled.value + if (isAutoRefreshEnabled.value) { + startAutoRefresh() + } else { + stopAutoRefresh() + } + } + + onMounted(() => { + store.fetchMetrics() + startAutoRefresh() + }) + + onUnmounted(() => { + stopAutoRefresh() + }) + + return { + metrics: store.metrics, + isLoading: store.isLoading, + healthScore: store.healthScore, + isHealthy: store.isHealthy, + isAutoRefreshEnabled, + refreshMetrics: store.fetchMetrics, + toggleAutoRefresh + } +} +``` + +## Registering Plugins + +Add your plugin to the plugin loader: + +```typescript +// src/plugins/index.ts +import type { Plugin } from '../plugin-system/types' +import HelloWorldPlugin from './hello-world' +import McpMetricsPlugin from './mcp-metrics-plugin' +import AdvancedPlugin from './advanced-plugin' + +export async function loadPlugins(): Promise { + return [ + new HelloWorldPlugin(), + new McpMetricsPlugin(), + new AdvancedPlugin(), + // Add more plugins here + ] +} +``` + +## Testing Plugins + +### Unit Testing Plugin Components + +```typescript +// tests/plugins/mcp-metrics-plugin/MetricsWidget.test.ts +import { mount } from '@vue/test-utils' +import { createPinia, setActivePinia } from 'pinia' +import MetricsWidget from '@/plugins/mcp-metrics-plugin/components/MetricsWidget.vue' + +describe('MetricsWidget', () => { + beforeEach(() => { + setActivePinia(createPinia()) + }) + + it('should render metrics correctly', async () => { + const wrapper = mount(MetricsWidget) + + // Wait for component to load + await wrapper.vm.$nextTick() + + expect(wrapper.find('.metrics-widget').exists()).toBe(true) + expect(wrapper.text()).toContain('MCP Server Metrics') + }) + + it('should show loading state initially', () => { + const wrapper = mount(MetricsWidget) + expect(wrapper.find('.animate-pulse').exists()).toBe(true) + }) + + it('should handle refresh button click', async () => { + const wrapper = mount(MetricsWidget) + const refreshButton = wrapper.find('button') + + await refreshButton.trigger('click') + expect(wrapper.vm.isLoading).toBe(true) + }) +}) +``` + +### Integration Testing + +```typescript +// tests/plugins/mcp-metrics-plugin/integration.test.ts +import { mount } from '@vue/test-utils' +import { createRouter, createWebHistory } from 'vue-router' +import { createPinia } from 'pinia' +import McpMetricsPlugin from '@/plugins/mcp-metrics-plugin' +import { PluginManager } from '@/plugin-system/PluginManager' + +describe('MCP Metrics Plugin Integration', () => { + let pluginManager: PluginManager + let router: any + let pinia: any + + beforeEach(() => { + router = createRouter({ + history: createWebHistory(), + routes: [] + }) + pinia = createPinia() + pluginManager = new PluginManager() + }) + + it('should initialize plugin successfully', async () => { + const plugin = new McpMetricsPlugin() + + await expect( + plugin.initialize(null as any, router, pinia, pluginManager) + ).resolves.not.toThrow() + + // Check if routes were added + const routes = router.getRoutes() + expect(routes.some((route: any) => route.name === 'Metrics')).toBe(true) + }) + + it('should register extension points', async () => { + const plugin = new McpMetricsPlugin() + await plugin.initialize(null as any, router, pinia, pluginManager) + + // Verify extension points were registered + const dashboardExtensions = pluginManager.getExtensionPoints('dashboard-widgets') + expect(dashboardExtensions).toHaveLength(1) + expect(dashboardExtensions[0].pluginId).toBe(plugin.meta.id) + }) +}) +``` + +### Plugin Store Testing + +```typescript +// tests/plugins/mcp-metrics-plugin/store.test.ts +import { createPinia, setActivePinia } from 'pinia' +import { useMetricsStore } from '@/plugins/mcp-metrics-plugin/store' + +describe('Metrics Store', () => { + beforeEach(() => { + setActivePinia(createPinia()) + }) + + it('should initialize with default values', () => { + const store = useMetricsStore() + + expect(store.metrics.totalServers).toBe(0) + expect(store.metrics.activeDeployments).toBe(0) + expect(store.isLoading).toBe(false) + expect(store.lastUpdated).toBeNull() + }) + + it('should update metrics after fetching', async () => { + const store = useMetricsStore() + + await store.fetchMetrics() + + expect(store.metrics.totalServers).toBeGreaterThan(0) + expect(store.lastUpdated).toBeInstanceOf(Date) + }) + + it('should calculate health score correctly', async () => { + const store = useMetricsStore() + + // Set known values for testing + store.metrics.uptime = '99.5%' + store.metrics.errorRate = '0.1%' + + expect(store.healthScore).toBeCloseTo(98.5) + expect(store.isHealthy).toBe(true) + }) +}) +``` + +## Plugin Development Best Practices + +### 1. Plugin Naming and Structure + +```typescript +// Good plugin naming +class McpServerMonitoringPlugin implements Plugin { + meta = { + id: 'mcp-server-monitoring', // kebab-case + name: 'MCP Server Monitoring', // Human readable + version: '1.2.3', // Semantic versioning + description: 'Real-time monitoring for MCP servers', // Clear description + author: 'DeployStack Team' + } +} + +// Avoid generic names +// ❌ class UtilsPlugin +// ❌ class MyPlugin +// ❌ class Plugin1 +``` + +### 2. Component Naming Convention + +```vue + + + + + + + + + +``` + +### 3. Error Handling + +```typescript +class RobustPlugin implements Plugin { + async initialize(app: App, router: Router, pinia: Pinia) { + try { + // Plugin initialization logic + await this.setupComponents() + await this.registerRoutes(router) + await this.initializeStore(pinia) + + console.log(`${this.meta.name} initialized successfully`) + } catch (error) { + console.error(`Failed to initialize ${this.meta.name}:`, error) + + // Graceful degradation + this.handleInitializationError(error) + + // Don't throw unless it's critical + // throw error + } + } + + private handleInitializationError(error: Error) { + // Log detailed error information + console.error('Plugin initialization error details:', { + pluginId: this.meta.id, + version: this.meta.version, + error: error.message, + stack: error.stack + }) + + // Maybe show a user notification + // Maybe disable certain features + // Maybe use fallback functionality + } +} +``` + +### 4. Resource Cleanup + +```typescript +class CleanPlugin implements Plugin { + private intervals: number[] = [] + private eventListeners: Array<{ element: EventTarget, type: string, listener: EventListener }> = [] + + async initialize(app: App, router: Router, pinia: Pinia) { + // Set up intervals + const intervalId = setInterval(() => { + this.refreshData() + }, 30000) + this.intervals.push(intervalId) + + // Set up event listeners + const listener = (event: Event` +}) => this.handleEvent(event) + document.addEventListener('visibilitychange', listener) + this.eventListeners.push({ + element: document, + type: 'visibilitychange', + listener + }) + } + + async cleanup() { + // Clean up intervals + this.intervals.forEach(id => clearInterval(id)) + this.intervals = [] + + // Clean up event listeners + this.eventListeners.forEach(({ element, type, listener }) => { + element.removeEventListener(type, listener) + }) + this.eventListeners = [] + + console.log(`${this.meta.name} cleaned up successfully`) + } +} +``` + +### 5. Type Safety + +```typescript +// Define clear interfaces for your plugin data +interface MetricsData { + totalServers: number + activeDeployments: number + totalRequests: number + responseTime: string + uptime: string + errorRate: string + throughput: string +} + +interface PluginConfig { + refreshInterval?: number + enableNotifications?: boolean + apiEndpoint?: string +} + +// Use proper typing in components +interface Props { + data: MetricsData + config?: PluginConfig + onRefresh?: () => void +} + +const props = withDefaults(defineProps(), { + config: () => ({}), + onRefresh: () => {} +}) +``` + +### 6. Performance Considerations + +```typescript +class PerformantPlugin implements Plugin { + private cache = new Map() + private readonly CACHE_DURATION = 30000 // 30 seconds + + async fetchData(key: string): Promise { + // Check cache first + const cached = this.cache.get(key) + if (cached && Date.now() - cached.timestamp < this.CACHE_DURATION) { + return cached.data + } + + // Fetch fresh data + const data = await this.performApiCall(key) + + // Update cache + this.cache.set(key, { + data, + timestamp: Date.now() + }) + + return data + } + + private async performApiCall(key: string): Promise { + // Actual API call implementation + const response = await fetch(`/api/plugin-data/${key}`) + return response.json() + } +} +``` + +## Plugin Lifecycle Management + +### Initialization Order + +Plugins are initialized in the order they're listed in the plugin loader, but you can control dependencies: + +```typescript +// In your plugin loader +export async function loadPlugins(): Promise { + const plugins = [ + new CorePlugin(), // Initialize first (no dependencies) + new MetricsPlugin(), // Depends on core + new AdvancedPlugin(), // Depends on metrics + ] + + // Sort by dependencies if needed + return sortPluginsByDependencies(plugins) +} + +function sortPluginsByDependencies(plugins: Plugin[]): Plugin[] { + // Implementation to sort plugins based on their dependencies + // This ensures plugins are initialized in the correct order + return plugins // simplified for example +} +``` + +### Runtime Plugin Management + +```typescript +// Enable/disable plugins at runtime +class PluginManager { + private activePlugins = new Map() + + async enablePlugin(pluginId: string): Promise { + const plugin = this.getAvailablePlugin(pluginId) + if (!plugin) { + throw new Error(`Plugin ${pluginId} not found`) + } + + if (this.activePlugins.has(pluginId)) { + console.warn(`Plugin ${pluginId} is already enabled`) + return + } + + await plugin.initialize(this.app, this.router, this.pinia, this) + this.activePlugins.set(pluginId, plugin) + + console.log(`Plugin ${pluginId} enabled successfully`) + } + + async disablePlugin(pluginId: string): Promise { + const plugin = this.activePlugins.get(pluginId) + if (!plugin) { + console.warn(`Plugin ${pluginId} is not currently enabled`) + return + } + + await plugin.cleanup() + this.activePlugins.delete(pluginId) + + // Remove extension points + this.removePluginExtensionPoints(pluginId) + + console.log(`Plugin ${pluginId} disabled successfully`) + } +} +``` + +## Plugin Distribution + +### Plugin Packaging + +Create a proper plugin package structure: + +```bash +my-plugin-package/ +├── package.json # NPM package configuration +├── README.md # Plugin documentation +├── CHANGELOG.md # Version history +├── LICENSE # License file +├── src/ +│ ├── index.ts # Main plugin export +│ ├── components/ # Plugin components +│ ├── stores/ # Plugin stores +│ └── types/ # Plugin types +├── dist/ # Compiled plugin (generated) +├── docs/ # Additional documentation +└── examples/ # Usage examples +``` + +### Package.json for Plugin + +```json +{ + "name": "@deploystack/mcp-metrics-plugin", + "version": "1.0.0", + "description": "MCP server metrics and analytics plugin for DeployStack", + "main": "dist/index.js", + "types": "dist/index.d.ts", + "scripts": { + "build": "tsc", + "dev": "tsc --watch", + "lint": "eslint src/**/*.ts", + "test": "vitest" + }, + "keywords": [ + "deploystack", + "plugin", + "mcp", + "metrics", + "analytics" + ], + "peerDependencies": { + "vue": "^3.3.0", + "vue-router": "^4.2.0", + "pinia": "^2.1.0" + }, + "devDependencies": { + "@types/vue": "^3.3.0", + "typescript": "^5.0.0", + "vite": "^4.3.0" + } +} +``` + +### Plugin Registry + +For team-wide plugin sharing: + +```typescript +// Plugin registry service +export class PluginRegistry { + private static instance: PluginRegistry + private plugins = new Map() + + static getInstance(): PluginRegistry { + if (!this.instance) { + this.instance = new PluginRegistry() + } + return this.instance + } + + register(plugin: Plugin): void { + if (this.plugins.has(plugin.meta.id)) { + throw new Error(`Plugin ${plugin.meta.id} is already registered`) + } + + this.plugins.set(plugin.meta.id, plugin) + console.log(`Plugin ${plugin.meta.id} registered successfully`) + } + + getPlugin(id: string): Plugin | undefined { + return this.plugins.get(id) + } + + getAllPlugins(): Plugin[] { + return Array.from(this.plugins.values()) + } + + getPluginsByAuthor(author: string): Plugin[] { + return this.getAllPlugins().filter(plugin => plugin.meta.author === author) + } +} +``` + +## Troubleshooting + +### Common Issues + +#### Plugin Not Loading + +```typescript +// Debug plugin loading +export async function loadPlugins(): Promise { + const plugins: Plugin[] = [] + + try { + const HelloWorldPlugin = (await import('./hello-world')).default + plugins.push(new HelloWorldPlugin()) + console.log('✅ HelloWorldPlugin loaded') + } catch (error) { + console.error('❌ Failed to load HelloWorldPlugin:', error) + } + + try { + const MetricsPlugin = (await import('./mcp-metrics-plugin')).default + plugins.push(new MetricsPlugin()) + console.log('✅ MetricsPlugin loaded') + } catch (error) { + console.error('❌ Failed to load MetricsPlugin:', error) + } + + return plugins +} +``` + +#### Extension Points Not Rendering + +```vue + + + + +``` + +#### Plugin State Issues + +```typescript +// Debug plugin state +class DebuggablePlugin implements Plugin { + async initialize(app: App, router: Router, pinia: Pinia) { + // Add global debug method + app.config.globalProperties.$debugPlugin = (pluginId: string) => { + console.log('Plugin Debug Info:', { + id: this.meta.id, + routes: router.getRoutes().filter(r => r.meta?.pluginId === pluginId), + stores: pinia._s, + extensionPoints: this.getRegisteredExtensionPoints() + }) + } + } + + private getRegisteredExtensionPoints() { + // Return extension points registered by this plugin + return [] + } +} +``` + +### Performance Debugging + +```typescript +// Performance monitoring for plugins +class PerformanceMonitoredPlugin implements Plugin { + async initialize(app: App, router: Router, pinia: Pinia) { + const startTime = performance.now() + + try { + await this.doInitialization() + + const endTime = performance.now() + console.log(`${this.meta.id} initialization took ${endTime - startTime}ms`) + } catch (error) { + const endTime = performance.now() + console.error(`${this.meta.id} failed after ${endTime - startTime}ms:`, error) + throw error + } + } + + private async doInitialization() { + // Your plugin initialization logic + } +} +``` + +This comprehensive plugin system documentation provides everything needed to create powerful, maintainable, and well-tested plugins for the DeployStack frontend. The modular architecture ensures that functionality can be extended cleanly while maintaining the core application's stability and performance. diff --git a/docs/deploystack/development/frontend/router-optimization.mdx b/docs/deploystack/development/frontend/router-optimization.mdx new file mode 100644 index 0000000..0117876 --- /dev/null +++ b/docs/deploystack/development/frontend/router-optimization.mdx @@ -0,0 +1,1022 @@ +--- +title: Router Optimization & Authentication Caching +description: Complete guide to the router performance optimizations and smart authentication caching system implemented in DeployStack frontend. +--- + +# Router Optimization & Authentication Caching + +This guide documents the comprehensive optimization implemented to eliminate unnecessary API calls and improve navigation performance in the DeployStack frontend, particularly focusing on authentication flows and route-specific optimizations. + +## Overview + +The DeployStack frontend implements a smart caching and route optimization system that significantly reduces API calls while maintaining security and data freshness. This system addresses performance bottlenecks in user authentication flows and provides an optimal user experience. + +## Problem Analysis + +### Original Performance Issues + +Before optimization, the frontend exhibited several performance problems: + +1. **Redundant Authentication Calls**: `GET /api/users/me` was called multiple times during single navigation events +2. **Unnecessary Public Route Checks**: Authentication verification on routes like `/login` and `/register` where users shouldn't be authenticated +3. **Team Data Over-fetching**: `GET /api/users/me/teams` was called repeatedly across component mounts +4. **Router Guard Inefficiency**: Navigation guards performed duplicate user checks within the same routing cycle + +### Performance Impact Measurements + +- **2+ API calls per navigation**: Router navigation guard was making redundant authentication checks +- **Backend load**: Unauthenticated requests unnecessarily hitting the backend +- **Poor user experience**: Network delays affecting navigation responsiveness +- **Console pollution**: Authentication errors on public routes cluttering browser console + +## Solution Architecture + +### 1. Smart Caching Strategy + +The optimization implements an intelligent caching system with the following characteristics: + +#### Cache Design Principles + +```typescript +interface CacheEntry { + data: User | null + timestamp: number + promise?: Promise +} + +interface CacheConfiguration { + duration: number // Cache validity period (30 seconds) + maxSize: number // Maximum cache entries (memory limit) + autoInvalidate: boolean // Automatic invalidation on auth changes +} +``` + +#### Cache Implementation + +- **Memory-only storage**: No persistent storage to maintain security +- **Short expiration**: 30-second cache duration balances performance and freshness +- **Request deduplication**: Prevents concurrent identical API requests +- **Automatic invalidation**: Cache cleared on login/logout events +- **Force refresh capability**: Override cache when fresh data is required + +### 2. Route Classification System + +Routes are intelligently classified to optimize authentication checking: + +#### Public Routes + +Routes that don't require user authentication: + +```typescript +const publicRoutes = ['Setup', 'Login', 'Register'] + +// Characteristics: +// - Skip user authentication checks entirely +// - Only verify database setup status +// - Zero unnecessary API calls +// - Optimal performance for anonymous users +``` + +#### Protected Routes + +Routes requiring authentication and authorization: + +```typescript +// Characteristics: +// - Single authentication check per navigation +// - Cached user data reused for role verification +// - Maintains all security requirements +// - Optimized for authenticated users +``` + +### 3. Navigation Guard Optimization + +The router navigation guard has been restructured for optimal performance: + +```typescript +router.beforeEach(async (to, from, next) => { + const publicRoutes = ['Setup', 'Login', 'Register'] + const isPublicRoute = publicRoutes.includes(to.name as string) + + // For public routes: skip authentication entirely + if (isPublicRoute) { + // Only check database setup if required + if (to.meta.requiresSetup) { + const setupRequired = await checkDatabaseSetup() + if (setupRequired && to.name !== 'Setup') { + return next({ name: 'Setup' }) + } + } + return next() + } + + // For protected routes: single authentication check + let currentUser = null + try { + currentUser = await UserService.getCurrentUser() // Uses cache + } catch (error) { + console.error('Authentication check failed:', error) + return next({ name: 'Login' }) + } + + // Reuse currentUser for role checks (no additional API calls) + if (to.meta.requiresRole && !userHasRole(currentUser, to.meta.requiresRole)) { + return next({ name: 'Unauthorized' }) + } + + next() +}) +``` + +## Implementation Details + +### User Service Caching + +#### Cache Management + +```typescript +export class UserService { + private static cache: CacheEntry | null = null + private static readonly CACHE_DURATION = 30000 // 30 seconds + private static pendingRequest: Promise | null = null + + static async getCurrentUser(forceRefresh = false): Promise { + // Force refresh bypasses cache + if (forceRefresh) { + this.clearCache() + } + + // Return cached data if valid + if (this.isCacheValid() && this.cache) { + return this.cache.data + } + + // Prevent concurrent requests + if (this.pendingRequest) { + return this.pendingRequest + } + + // Make fresh API call + this.pendingRequest = this.fetchCurrentUser() + const user = await this.pendingRequest + + // Cache the result + this.cache = { + data: user, + timestamp: Date.now() + } + + this.pendingRequest = null + return user + } + + private static isCacheValid(): boolean { + return this.cache !== null && + Date.now() - this.cache.timestamp < this.CACHE_DURATION + } + + static clearCache(): void { + this.cache = null + this.pendingRequest = null + // Also clear team cache since teams are user-specific + TeamService.clearUserTeamsCache() + } + + private static async fetchCurrentUser(): Promise { + try { + const response = await fetch('/api/users/me') + if (!response.ok) { + if (response.status === 401) { + return null // User not authenticated + } + throw new Error(`HTTP ${response.status}: ${response.statusText}`) + } + return await response.json() + } catch (error) { + console.error('Failed to fetch current user:', error) + throw error + } + } +} +``` + +#### Authentication Methods + +```typescript +export class UserService { + static async login(email: string, password: string): Promise { + const response = await fetch('/api/auth/login', { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ email, password }) + }) + + if (!response.ok) { + throw new Error('Login failed') + } + + const user = await response.json() + + // Clear cache to ensure fresh data after login + this.clearCache() + + return user + } + + static async logout(): Promise { + await fetch('/api/auth/logout', { method: 'POST' }) + + // Clear all user-related cache + this.clearCache() + } +} +``` + +### Team Service Caching + +The team service implements similar caching patterns for team-related data: + +```typescript +export class TeamService { + private static userTeamsCache: TeamCacheEntry | null = null + private static readonly CACHE_DURATION = 30000 + private static pendingUserTeamsRequest: Promise | null = null + + static async getUserTeams(forceRefresh = false): Promise { + if (forceRefresh) { + this.clearUserTeamsCache() + } + + if (this.isUserTeamsCacheValid() && this.userTeamsCache) { + return this.userTeamsCache.data + } + + if (this.pendingUserTeamsRequest) { + return this.pendingUserTeamsRequest + } + + this.pendingUserTeamsRequest = this.fetchUserTeams() + const teams = await this.pendingUserTeamsRequest + + this.userTeamsCache = { + data: teams, + timestamp: Date.now() + } + + this.pendingUserTeamsRequest = null + return teams + } + + // CRUD operations automatically clear cache + static async createTeam(teamData: CreateTeamRequest): Promise { + const response = await fetch('/api/teams', { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify(teamData) + }) + + if (!response.ok) { + throw new Error('Failed to create team') + } + + const team = await response.json() + + // Clear cache to ensure fresh team list + this.clearUserTeamsCache() + + return team + } + + static clearUserTeamsCache(): void { + this.userTeamsCache = null + this.pendingUserTeamsRequest = null + } +} +``` + +### Component Integration + +#### Sidebar Component Optimization + +```vue + + + + +``` + +## Performance Improvements + +### Measured Performance Gains + +#### Before Optimization + +- **Login page navigation**: 2 API calls to `/api/users/me` +- **Register page navigation**: 2 API calls to `/api/users/me` +- **Protected route navigation**: 3+ API calls per navigation +- **Team data fetching**: Multiple calls to `/api/users/me/teams` +- **Backend error rate**: High due to unauthenticated requests + +#### After Optimization + +- **Public routes**: 0 API calls to `/api/users/me` +- **Protected routes**: 1 API call per 30-second window (cached) +- **Navigation speed**: 60-80% faster due to eliminated network delays +- **Backend efficiency**: 70% reduction in authentication-related requests +- **Error reduction**: 100% elimination of authentication errors on public routes + +### Performance Metrics + +| Metric | Before | After | Improvement | +|--------|--------|-------|-------------| +| API calls per login navigation | 2 | 0 | 100% reduction | +| API calls per protected route | 2-3 | 1 (cached) | 50-66% reduction | +| Navigation speed | ~500ms | ~100ms | 80% faster | +| Backend authentication load | High | Low | 70% reduction | +| Console errors | Multiple | None | 100% elimination | + +## Usage Guidelines + +### When to Use Cached vs Fresh Data + +#### Use Cached Data (Default Behavior) + +```typescript +// Standard navigation and component mounting +const user = await UserService.getCurrentUser() +const teams = await TeamService.getUserTeams() + +// Most UI components should use cached data +const currentUser = await UserService.getCurrentUser() +``` + +#### Force Fresh Data + +```typescript +// After user profile updates +const user = await UserService.getCurrentUser(true) + +// After team modifications +const teams = await TeamService.getUserTeams(true) + +// In user account settings page +onMounted(async () => { + user.value = await UserService.getCurrentUser(true) // Always fresh +}) + +// After role changes +await UserService.clearCache() +const user = await UserService.getCurrentUser() +``` + +### Route Configuration + +#### Adding New Public Routes + +```typescript +// In router/index.ts +const publicRoutes = ['Setup', 'Login', 'Register', 'ForgotPassword', 'NewPublicRoute'] + +// No additional configuration needed - route automatically skips auth checks +``` + +#### Adding New Protected Routes + +```typescript +// Routes are protected by default +router.addRoute({ + path: '/dashboard', + name: 'Dashboard', + component: Dashboard, + meta: { + requiresAuth: true, // Optional - implied for non-public routes + requiresRole: 'admin', // Optional - for role-based access + requiresSetup: true // Optional - for database requirement + } +}) +``` + +### Component Best Practices + +#### Efficient User Data Loading + +```vue + +``` + +#### Manual Cache Management + +```vue + +``` + +## Advanced Configuration + +### Cache Duration Tuning + +The cache duration can be adjusted based on your application's needs: + +```typescript +export class UserService { + // Current: 30 seconds (balanced approach) + private static readonly CACHE_DURATION = 30000 + + // Shorter duration for high-security applications + private static readonly CACHE_DURATION = 10000 // 10 seconds + + // Longer duration for applications with stable user data + private static readonly CACHE_DURATION = 60000 // 1 minute +} +``` + +#### Cache Duration Considerations + +| Duration | Pros | Cons | Best For | +|----------|------|------|----------| +| 10 seconds | Fresh data, high security | More API calls | High-security apps | +| 30 seconds | Balanced performance/freshness | Default choice | Most applications | +| 60 seconds | Fewer API calls, better performance | Potentially stale data | Stable environments | + +### Environment-Specific Configuration + +```typescript +// Configure cache based on environment +const getCacheDuration = (): number => { + const env = import.meta.env.MODE + + switch (env) { + case 'development': + return 10000 // Shorter cache for development + case 'production': + return 30000 // Standard cache for production + case 'testing': + return 0 // No cache for testing + default: + return 30000 + } +} + +export class UserService { + private static readonly CACHE_DURATION = getCacheDuration() +} +``` + +### Cache Statistics and Monitoring + +```typescript +export class UserService { + private static cacheStats = { + hits: 0, + misses: 0, + invalidations: 0 + } + + static getCacheStats() { + const total = this.cacheStats.hits + this.cacheStats.misses + return { + ...this.cacheStats, + hitRate: total > 0 ? (this.cacheStats.hits / total) * 100 : 0 + } + } + + static async getCurrentUser(forceRefresh = false): Promise { + if (!forceRefresh && this.isCacheValid() && this.cache) { + this.cacheStats.hits++ + return this.cache.data + } + + this.cacheStats.misses++ + // ... rest of implementation + } + + static clearCache(): void { + this.cacheStats.invalidations++ + this.cache = null + this.pendingRequest = null + } +} +``` + +## Security Considerations + +### Cache Security + +The caching implementation maintains security through several mechanisms: + +#### Memory-Only Storage + +```typescript +// ✅ Secure: Cache stored in memory only +private static cache: CacheEntry | null = null + +// ❌ Insecure: Don't store sensitive data in persistent storage +// localStorage.setItem('userCache', JSON.stringify(user)) +// sessionStorage.setItem('userCache', JSON.stringify(user)) +``` + +#### Automatic Cache Invalidation + +```typescript +// Cache is automatically cleared on authentication state changes +static async login(email: string, password: string): Promise { + const user = await this.performLogin(email, password) + this.clearCache() // Ensure fresh data after login + return user +} + +static async logout(): Promise { + await this.performLogout() + this.clearCache() // Clear potentially sensitive cached data +} +``` + +#### Short Cache Duration + +```typescript +// Cache expires quickly to minimize stale data risks +private static readonly CACHE_DURATION = 30000 // 30 seconds only +``` + +### Authentication Security + +All authentication security measures are preserved: + +#### Session Management + +```typescript +// Authentication still relies on secure server-side sessions +// Cache only stores non-sensitive user metadata +// Actual authentication happens on every cache miss +``` + +#### Role-Based Access Control + +```typescript +// Role checks still use fresh user data when needed +if (to.meta.requiresRole) { + const currentUser = await UserService.getCurrentUser() // May use cache + if (!userHasRole(currentUser, to.meta.requiresRole)) { + return next({ name: 'Unauthorized' }) + } +} +``` + +#### Public Route Protection + +```typescript +// Public routes properly skip authentication +// No security bypass - just optimization +if (isPublicRoute) { + return next() // Skip auth checks, but don't bypass other security +} +``` + +## Debugging and Troubleshooting + +### Cache Debugging + +Enable cache debugging during development: + +```typescript +export class UserService { + private static debug = import.meta.env.MODE === 'development' + + static async getCurrentUser(forceRefresh = false): Promise { + if (this.debug) { + console.log('UserService.getCurrentUser:', { + forceRefresh, + hasCachedData: !!this.cache, + isCacheValid: this.isCacheValid(), + cacheAge: this.cache ? Date.now() - this.cache.timestamp : 'N/A', + pendingRequest: !!this.pendingRequest + }) + } + + // ... rest of implementation + } +} +``` + +### Network Monitoring + +Monitor API calls to verify optimization: + +```typescript +// Add network monitoring in development +if (import.meta.env.MODE === 'development') { + const originalFetch = window.fetch + window.fetch = function(...args) { + const url = args[0] + if (typeof url === 'string' && url.includes('/api/users/me')) { + console.log('🌐 API Call:', url, new Date().toISOString()) + } + return originalFetch.apply(this, args) + } +} +``` + +### Common Issues and Solutions + +#### Issue: User Data Seems Stale + +**Symptoms**: User interface shows outdated information after profile changes + +**Solution**: Force refresh after data modifications + +```typescript +// After updating user profile +await updateUserProfile(profileData) +const freshUser = await UserService.getCurrentUser(true) +``` + +#### Issue: Too Many API Calls + +**Symptoms**: Still seeing frequent `/api/users/me` calls + +**Diagnosis**: Check if components are forcing refresh unnecessarily + +```typescript +// ❌ Problem: Always forcing refresh +const user = await UserService.getCurrentUser(true) + +// ✅ Solution: Use cached data when appropriate +const user = await UserService.getCurrentUser() +``` + +#### Issue: Authentication Not Working After Login + +**Symptoms**: User redirected to login page after successful authentication + +**Diagnosis**: Cache not cleared after login + +```typescript +// ✅ Ensure login method clears cache +static async login(email: string, password: string): Promise { + const response = await fetch('/api/auth/login', { /* ... */ }) + const user = await response.json() + + // This is crucial + this.clearCache() + + return user +} +``` + +#### Issue: Cache Not Working + +**Symptoms**: Still seeing API calls within cache duration + +**Diagnosis**: Check cache validation logic + +```typescript +// Debug cache validation +private static isCacheValid(): boolean { + const isValid = this.cache !== null && + Date.now() - this.cache.timestamp < this.CACHE_DURATION + + if (import.meta.env.MODE === 'development') { + console.log('Cache validation:', { + hasCache: !!this.cache, + age: this.cache ? Date.now() - this.cache.timestamp : 'N/A', + duration: this.CACHE_DURATION, + isValid + }) + } + + return isValid +} +``` + +### Performance Testing + +#### Manual Testing + +Test the optimization by monitoring network requests: + +1. **Open browser DevTools** → Network tab +2. **Filter requests** by `/api/users/me` +3. **Navigate to login page** → Should see 0 requests +4. **Navigate to protected route** → Should see 1 request +5. **Navigate between protected routes** → Should see 0 additional requests (within 30 seconds) + +#### Automated Testing + +```typescript +// Test cache behavior +describe('UserService Caching', () => { + beforeEach(() => { + UserService.clearCache() + vi.clearAllMocks() + }) + + it('should cache user data', async () => { + const mockFetch = vi.fn().mockResolvedValue({ + ok: true, + json: () => Promise.resolve({ id: 1, name: 'Test User' }) + }) + global.fetch = mockFetch + + // First call should hit API + const user1 = await UserService.getCurrentUser() + expect(mockFetch).toHaveBeenCalledTimes(1) + + // Second call should use cache + const user2 = await UserService.getCurrentUser() + expect(mockFetch).toHaveBeenCalledTimes(1) // Still only 1 call + expect(user1).toEqual(user2) + }) + + it('should invalidate cache on logout', async () => { + const mockFetch = vi.fn() + .mockResolvedValueOnce({ + ok: true, + json: () => Promise.resolve({ id: 1, name: 'Test User' }) + }) + .mockResolvedValueOnce({ ok: true }) // logout response + .mockResolvedValueOnce({ + ok: false, + status: 401 + }) + + global.fetch = mockFetch + + // Get user (cached) + await UserService.getCurrentUser() + + // Logout (clears cache) + await UserService.logout() + + // Next call should hit API with fresh request + await UserService.getCurrentUser().catch(() => {}) // Expect 401 + expect(mockFetch).toHaveBeenCalledTimes(3) + }) +}) +``` + +## Migration Guide + +### Migrating Existing Components + +If you have existing components that fetch user data, update them to use the optimized service: + +#### Before (Manual Fetch) + +```vue + +``` + +#### After (Optimized Service) + +```vue + +``` + +### Router Guard Migration + +#### Before (Multiple API Calls) + +```typescript +router.beforeEach(async (to, from, next) => { + // First API call + const user = await fetchCurrentUser() + if (user && (to.name === 'Login' || to.name === 'Register')) { + return next({ name: 'Dashboard' }) + } + + // Second API call + const currentUser = await fetchCurrentUser() + if (to.meta.requiresAuth && !currentUser) { + return next({ name: 'Login' }) + } + + next() +}) +``` + +#### After (Single Cached Call) + +```typescript +router.beforeEach(async (to, from, next) => { + const publicRoutes = ['Setup', 'Login', 'Register'] + const isPublicRoute = publicRoutes.includes(to.name as string) + + if (isPublicRoute) { + return next() // Skip auth checks entirely + } + + // Single API call (cached) + const currentUser = await UserService.getCurrentUser() + if (!currentUser) { + return next({ name: 'Login' }) + } + + // Reuse currentUser for additional checks + if (to.meta.requiresRole && !userHasRole(currentUser, to.meta.requiresRole)) { + return next({ name: 'Unauthorized' }) + } + + next() +}) +``` + +## Maintenance and Monitoring + +### Regular Performance Reviews + +#### Monthly Checklist + +- [ ] Review cache hit/miss ratios in production +- [ ] Monitor API call patterns in analytics +- [ ] Check for new routes that need classification +- [ ] Validate authentication flow performance +- [ ] Update cache duration if needed + +#### Performance Metrics to Track + +1. **API Call Frequency**: Monitor `/api/users/me` request patterns +2. **Cache Hit Rate**: Aim for >70% cache hit rate +3. **Navigation Speed**: Measure time-to-interactive for route changes +4. **Error Rates**: Monitor authentication-related errors +5. **User Experience**: Track user satisfaction with navigation speed + +### Future Enhancements + +#### Potential Improvements + +1. **Configurable Cache Duration**: Environment-based cache settings +2. **Background Refresh**: Proactively refresh cache before expiration +3. **Selective Cache Invalidation**: Invalidate only specific user properties +4. **Cache Warming**: Pre-load user data on application startup +5. **Real-time Updates**: WebSocket integration for live user data updates + +#### Advanced Caching Strategies + +```typescript +// Background refresh implementation +class AdvancedUserService extends UserService { + private static backgroundRefreshTimer: number | null = null + + static enableBackgroundRefresh() { + this.backgroundRefreshTimer = setInterval(async () => { + if (this.cache && this.isNearExpiration()) { + // Refresh cache in background before it expires + await this.getCurrentUser(true) + } + }, 10000) // Check every 10 seconds + } + + private static isNearExpiration(): boolean { + if (!this.cache) return false + const age = Date.now() - this.cache.timestamp + return age > (this.CACHE_DURATION * 0.8) // 80% of cache duration + } +} +``` + +This comprehensive router optimization and authentication caching system provides significant performance improvements while maintaining security and data freshness. The implementation demonstrates how thoughtful caching strategies can eliminate unnecessary API calls and create a more responsive user experience in modern web applications. diff --git a/docs/deploystack/development/index.mdx b/docs/deploystack/development/index.mdx new file mode 100644 index 0000000..862c2b5 --- /dev/null +++ b/docs/deploystack/development/index.mdx @@ -0,0 +1,138 @@ +--- +title: Development Guide +description: Complete development documentation for DeployStack - covering frontend, backend, and contribution guidelines for the MCP server deployment platform. +icon: FileCode +--- + +import { Card, Cards } from 'fumadocs-ui/components/card'; +import { Code2, Server, GitBranch, Users } from 'lucide-react'; + +# DeployStack Development + +Welcome to the DeployStack development documentation! DeployStack is the leading infrastructure platform for Model Context Protocol (MCP) server deployment, built with modern web technologies and an extensible architecture. + +## Architecture Overview + +DeployStack follows a modern full-stack architecture: + +- **Frontend**: Vue 3 + TypeScript + Vite for the user interface +- **Backend**: Fastify + TypeScript + SQLite/PostgreSQL for the API and data layer +- **MCP Focus**: Specialized CI/CD pipeline for MCP server deployments +- **Multi-Cloud**: Support for AWS, Render.com, Fly.io, DigitalOcean, and more + +## Development Areas + + + } + href="/deploystack/development/frontend" + title="Frontend Development" + > + Vue 3, TypeScript, and Vite development guide. UI components, state management, internationalization, and plugin system. + + + } + href="/deploystack/development/backend" + title="Backend Development" + > + Fastify, TypeScript, and Drizzle ORM development guide. API design, database management, authentication, and plugin architecture. + + + +## Getting Started + +### Prerequisites + +- Node.js 18 or higher +- npm 8 or higher +- Git for version control + +### Quick Setup + +```bash +# Clone the repository +git clone https://github.com/deploystackio/deploystack.git +cd deploystack + +# Install dependencies for both frontend and backend +npm install + +# Start development servers +npm run dev +``` + +This will start both the frontend (http://localhost:5173) and backend (http://localhost:3000) development servers. + +## Development Workflow + +1. **Choose Your Area**: Start with either frontend or backend development +2. **Set Up Environment**: Follow the specific setup guides for your chosen area +3. **Make Changes**: Implement features, fix bugs, or improve documentation +4. **Test**: Run the appropriate test suites +5. **Submit**: Create pull requests following our contribution guidelines + +## Project Structure + +```bash +deploystack/ +├── services/ +│ ├── frontend/ # Vue 3 frontend application +│ │ ├── src/ +│ │ ├── public/ +│ │ └── package.json +│ └── backend/ # Fastify backend API +│ ├── src/ +│ ├── plugins/ +│ └── package.json +├── docs/ # Documentation +└── docker-compose.yml # Development environment +``` + +## Key Technologies + +### Frontend Stack +- **Vue 3** with Composition API for reactive user interfaces +- **TypeScript** for type safety and better developer experience +- **Vite** for fast development and building +- **TailwindCSS** with shadcn-vue for consistent styling +- **Vue I18n** for internationalization support + +### Backend Stack +- **Fastify** for high-performance HTTP server +- **TypeScript** for type-safe server development +- **Drizzle ORM** for database operations and migrations +- **Zod** for request/response validation +- **Plugin System** for extensible functionality + +## Development Philosophy + +### MCP-First Approach +DeployStack is purpose-built for the Model Context Protocol ecosystem. Our development decisions prioritize: + +- **MCP Server Compatibility**: Seamless deployment of MCP servers +- **Security Isolation**: Plugin system with proper namespacing +- **Multi-Cloud Support**: Cloud provider agnostic deployments +- **Developer Experience**: Simple, one-click deployment workflows + +### Code Quality +- **Type Safety**: TypeScript throughout the stack +- **Testing**: Comprehensive test coverage +- **Documentation**: Clear, up-to-date documentation +- **Security**: Built-in security best practices + +## Contributing + +We welcome contributions to DeployStack! Whether you're: + +- **Adding Features**: New MCP server support, UI improvements, API enhancements +- **Fixing Bugs**: Issues with deployment, UI problems, API errors +- **Improving Documentation**: Better guides, examples, and explanations +- **Creating Plugins**: Extending DeployStack functionality + +## Community + +- **GitHub**: [deploystackio/deploystack](https://github.com/deploystackio/deploystack) +- **Issues**: Report bugs and request features + +For detailed development guides, choose your area of interest from the cards above. Each section contains comprehensive documentation for getting started, best practices, and advanced topics. diff --git a/docs/deploystack/global-settings.mdx b/docs/deploystack/global-settings.mdx new file mode 100644 index 0000000..072dd0e --- /dev/null +++ b/docs/deploystack/global-settings.mdx @@ -0,0 +1,135 @@ +--- +title: Global Settings +description: Manage your DeployStack application settings including email configuration, authentication, and system preferences in one central location. +--- + +# Global Settings + +Global Settings is your central control panel for configuring DeployStack. Here you can set up email delivery, manage authentication options, and control various system features. + +## What are Global Settings? + +Global Settings are configuration options that affect your entire DeployStack installation. Think of them as the "system preferences" for your deployment platform. These settings are organized into different categories (called groups) to make them easier to manage. + +## Accessing Global Settings + +To access Global Settings: + +1. **Log in** as an administrator +2. **Navigate** to the Settings section in your dashboard +3. **Select** the setting group you want to configure + +**Note**: Only users with administrator privileges can view and modify global settings. + +## Setting Groups + +Your settings are organized into logical groups that appear as tabs in the interface: + +### SMTP Mail Settings +Configure email delivery for notifications and user communications: + +- **SMTP Server**: Your email server address (like `smtp.gmail.com`) +- **Port**: Usually 587 for most email providers +- **Username & Password**: Your email account credentials +- **Sender Information**: The name and email address that appears on outgoing emails + +**Why this matters**: Email setup is essential for user registration confirmations, password resets, and system notifications. + +### GitHub OAuth Configuration +Set up GitHub login for your users: + +- **Client ID & Secret**: Credentials from your GitHub OAuth app +- **Enable/Disable**: Turn GitHub login on or off +- **Callback URL**: Where GitHub redirects users after login + +**Why this matters**: Allows users to sign in with their GitHub accounts instead of creating new passwords. + +### System Configuration +Control how DeployStack behaves: + +- **Frontend URL**: The web address where users access your DeployStack interface +- **Email Sending**: Enable or disable all email functionality +- **Login Options**: Control which login methods are available +- **API Documentation**: Show or hide the technical API documentation + +**Why this matters**: These settings control the basic behavior and security of your DeployStack installation. + +## Setting Up Email (SMTP) + +Email configuration is one of the most important settings to configure. Here's a simple guide: + +### For Gmail Users: +1. **SMTP Host**: `smtp.gmail.com` +2. **Port**: `587` +3. **Username**: Your Gmail address +4. **Password**: Use an "App Password" (not your regular Gmail password) +5. **Enable**: Set "Use TLS" to Yes + +### For Other Email Providers: +Check your email provider's SMTP settings documentation. Most business email providers offer SMTP access. + +## Setting Up GitHub Login + +To allow users to log in with GitHub: + +1. **Create a GitHub OAuth App**: + - Go to GitHub Settings > Developer settings > OAuth Apps + - Click "New OAuth App" + - Set the callback URL to: `https://your-deploystack-url.com/api/auth/github/callback` + +2. **Configure in DeployStack**: + - Enter the Client ID and Client Secret from GitHub + - Set the callback URL to match what you entered in GitHub + - Enable GitHub OAuth + +## Security Notes + +- **Sensitive Information**: Settings like passwords and API keys are automatically encrypted +- **Administrator Access**: Only administrators can view and change these settings +- **Backup**: Consider backing up your settings before making major changes + +## Common Settings Scenarios + +### Personal Use +- Enable email with your personal email account +- Disable GitHub OAuth (use email registration instead) +- Keep API documentation enabled for learning + +### Team Use +- Set up business email account for professional communications +- Enable GitHub OAuth for easier team member access +- Consider disabling email registration if you only want GitHub users + +### Production Use +- Use dedicated email service (like SendGrid or AWS SES) +- Enable GitHub OAuth for team access +- Disable API documentation for security +- Set proper frontend URL for your domain + +## Troubleshooting + +### Email Not Working +- Check your SMTP credentials are correct +- Verify your email provider allows SMTP access +- For Gmail, ensure you're using an App Password +- Check the "Test Email" feature if available + +### GitHub Login Issues +- Verify your GitHub OAuth app settings +- Ensure the callback URL matches exactly +- Check that the GitHub OAuth app is active + +### Can't Access Settings +- Confirm you have administrator privileges +- Check with the person who installed DeployStack +- The first user registered automatically becomes an administrator + +## Getting Help + +If you need assistance with Global Settings: + +- Check the troubleshooting section above +- Visit our [Discord community](https://discord.gg/UjFWwByB) +- Consult your system administrator if DeployStack was set up by someone else + +Remember: Changes to Global Settings affect your entire DeployStack installation, so test them carefully, especially email and authentication settings. diff --git a/docs/deploystack/index.mdx b/docs/deploystack/index.mdx index 2203faa..5f677c0 100644 --- a/docs/deploystack/index.mdx +++ b/docs/deploystack/index.mdx @@ -1,23 +1,46 @@ --- title: DeployStack Documentation -description: Official DeployStack documentation - Learn how to automate Docker Compose and run deployments across cloud providers. Clear guides and technical references for effective deployment automation. +description: Official DeployStack documentation - The first CI/CD platform designed for MCP servers. Deploy Model Context Protocol servers across cloud providers with one click. menuTitle: DeployStack --- -# DeployStack - Open Source Cloud Deployment Guide +# DeployStack - MCP Server CI/CD Platform -DeployStack helps you deploy Docker Compose and Docker Run applications across different cloud providers by automatically generating Infrastructure as Code templates. Our documentation guides you through using DeployStack effectively. +DeployStack is the first CI/CD platform specifically designed for Model Context Protocol (MCP) servers. We make it easy to deploy and manage MCP servers across different cloud providers, transforming complex technical processes into one-click solutions. -## Documentation Sections +## Quick Start + +**New to MCP servers?** Start here to understand how DeployStack simplifies MCP server deployment and management. + +- [Getting Started](/deploystack/getting-started) - Your first MCP server deployment +- [MCP Server Catalog](https://deploystack.io/mcp) - Browse ready-to-deploy MCP servers +- [One-Click Deploy](/deploystack/one-click-deploy) - Deploy any MCP server instantly + +## User Guides + +**For administrators and team members** using DeployStack: + +- [Global Settings](/deploystack/global-settings) - Configure email, authentication, and system preferences +- [User Roles and Permissions](/deploystack/roles) - Manage user access and team collaboration +- [Troubleshooting](/deploystack/troubleshooting) - Resolve common deployment issues + +## MCP Server Requirements + +**For MCP server creators** who want to make their servers deployable: -- [Getting Started](/deploystack/getting-started) - Quick introduction and first steps - [Docker Compose Requirements](/deploystack/docker-compose-requirements) - Learn about supported configurations -- [One-Click Deploy](/deploystack/one-click-deploy) - Learn about deployment automation -- [Troubleshooting](/deploystack/troubleshooting) - Resolve common issues +- [Submit Your MCP Server](https://deploystack.io/submit) - Add your server to our catalog + +## Developer Documentation + +**For developers** extending or contributing to DeployStack: + +- [Backend Development](/deploystack/development/backend) - API, database, plugins, and testing +- [Docker-to-IaC Module](/docker-to-iac/index) - Core deployment engine documentation ## Additional Resources -- [Docker-to-IaC Module Documentation](/docker-to-iac/index) -- [Join our Discord](https://discord.gg/UjFWwByB) -- [Visit DeployStack](https://deploystack.io) +- [Join our Discord](https://discord.gg/UjFWwByB) - Get help and connect with the community +- [Visit DeployStack](https://deploystack.io) - Main website and MCP server catalog +- [GitHub Repository](https://github.com/deploystackio/deploystack) - Contribute to the project diff --git a/docs/deploystack/meta.json b/docs/deploystack/meta.json index dbe3c80..87ea42c 100644 --- a/docs/deploystack/meta.json +++ b/docs/deploystack/meta.json @@ -2,5 +2,8 @@ "title": "Docker Deployment", "description": "Documentation for DeployStack", "icon": "DeployStackLogo", - "root": true + "root": true, + "pages": [ + "..." + ] } diff --git a/docs/deploystack/roles.mdx b/docs/deploystack/roles.mdx new file mode 100644 index 0000000..5ea934e --- /dev/null +++ b/docs/deploystack/roles.mdx @@ -0,0 +1,191 @@ +--- +title: User Roles and Permissions +description: Understand user roles, permissions, and team management in DeployStack. Learn how to manage access control and collaborate effectively. +--- + +# User Roles and Permissions + +DeployStack uses a role-based system to control what different users can do in your installation. This guide explains how roles work and how to manage user access. + +## What are User Roles? + +User roles determine what actions a person can perform in DeployStack. Think of roles as "job titles" that come with specific permissions. Each user is assigned one role that defines their level of access. + +## Available Roles + +### Global Administrator +**Who needs this**: The person responsible for managing the entire DeployStack installation. + +**What they can do**: +- Manage all users (create, edit, delete) +- Configure global settings (email, authentication, system options) +- Manage roles and permissions +- Access all system features +- Manage all teams + +**Important**: The first person to register automatically becomes a Global Administrator. + +### Global User +**Who needs this**: Regular users who want to deploy applications. + +**What they can do**: +- View and edit their own profile +- Create up to 3 teams +- Manage their own teams +- Deploy applications through their teams + +**Note**: This is the default role for new users. + +### Team Administrator +**Who needs this**: Users who manage specific teams within the organization. + +**What they can do**: +- Manage their team's settings +- View team members +- Manage team deployments +- Delete teams they own + +### Team User +**Who needs this**: Basic team members who participate in deployments. + +**What they can do**: +- View team information +- See team members +- Participate in team activities + +## Understanding Teams + +Teams are groups where users organize their deployment projects. Here's how teams work: + +### Team Basics +- **Automatic Team**: Every user gets their own team when they register +- **Team Limit**: Users can create up to 3 teams total +- **Team Owner**: The person who created the team has full control +- **Single User Teams**: Currently, each team has one user (multi-user teams coming soon) + +### Team Management +- **Create Teams**: Use descriptive names for your different projects +- **Team Settings**: Customize team name and description +- **Team Deletion**: Only team owners can delete teams + +## Common Role Scenarios + +### Personal Use +- **You are**: Global Administrator (first user) or Global User +- **Your teams**: Use your default team for personal projects +- **Additional teams**: Create separate teams for different types of projects + +### Small Team +- **Administrator**: One person manages the system and users +- **Team Members**: Everyone else is a Global User with their own teams +- **Collaboration**: Users can share deployment information outside the system + +### Organization +- **System Admin**: Global Administrator manages the DeployStack installation +- **Project Leads**: Team Administrators manage specific project teams +- **Developers**: Global Users participate in deployments + +## Managing User Roles + +### As a Global Administrator + +**To view all users**: +1. Go to User Management in your admin panel +2. See list of all registered users with their roles + +**To change a user's role**: +1. Find the user in the user list +2. Click on their role +3. Select the new role from the dropdown +4. Save changes + +**To create new users** (if needed): +1. Use the "Create User" option +2. Fill in their information +3. Assign appropriate role +4. User receives login information + +### Managing Your Own Profile +All users can: +- View their profile information +- Update their name and email +- Change their password +- See their current role (but not change it) + +## Team Management + +### Creating Teams +1. **Go to Teams** in your dashboard +2. **Click "Create Team"** +3. **Enter team name** and description +4. **Save** - you become the team owner automatically + +### Managing Your Teams +- **Edit team details**: Update name and description +- **View team information**: See team settings and members +- **Delete teams**: Remove teams you no longer need + +### Team Limitations +- **3 Team Maximum**: You can only create 3 teams total +- **One User per Team**: Teams currently support single users +- **Owner Control**: Only team owners can modify team settings + +## Security and Access Control + +### What Roles Protect +- **System Settings**: Only administrators can change global configuration +- **User Management**: Only administrators can create, edit, or delete users +- **Team Ownership**: Only team owners can modify their teams +- **Profile Privacy**: Users can only edit their own profiles + +### Role Assignment Rules +- **First User**: Automatically becomes Global Administrator +- **New Users**: Get Global User role by default +- **Self-Assignment**: Users cannot change their own roles +- **Admin Assignment**: Only administrators can change user roles + +## Troubleshooting Roles and Teams + +### Can't Access Settings +**Problem**: "I don't see the Settings option" +**Solution**: Only Global Administrators can access system settings. Contact your administrator. + +### Can't Create Teams +**Problem**: "Create Team button is disabled" +**Solution**: You may have reached the 3-team limit. Delete unused teams or contact your administrator. + +### Can't Change Role +**Problem**: "I want to be an administrator" +**Solution**: Only existing administrators can assign roles. Ask your current administrator to change your role. + +### Lost Administrator Access +**Problem**: "No one has administrator access" +**Solution**: This requires technical intervention. Contact your system administrator or technical support. + +## Best Practices + +### For Administrators +- **Regular Review**: Periodically review user roles and remove inactive users +- **Principle of Least Privilege**: Give users the minimum role needed for their tasks +- **Documentation**: Keep track of who has what role and why +- **Backup Access**: Ensure at least two people have administrator access + +### For Team Management +- **Descriptive Names**: Use clear team names that reflect their purpose +- **Regular Cleanup**: Delete teams you no longer use +- **Organization**: Consider how to organize your projects across teams + +### For Security +- **Role Changes**: Think carefully before changing someone's role +- **Team Ownership**: Be aware that team owners have full control over their teams +- **Profile Information**: Keep your profile information current + +## Getting Help + +If you have questions about roles or teams: + +- **Role Questions**: Contact your Global Administrator +- **Technical Issues**: Visit our [Discord community](https://discord.gg/UjFWwByB) +- **Feature Requests**: Let us know what team features you'd like to see + +Remember: The role system is designed to be simple but secure. Most users will be happy as Global Users with their own teams, while administrators handle system-wide configuration. diff --git a/docs/deploystack/security.mdx b/docs/deploystack/security.mdx new file mode 100644 index 0000000..1cd74c4 --- /dev/null +++ b/docs/deploystack/security.mdx @@ -0,0 +1,187 @@ +--- +title: Security and Privacy +description: Learn how DeployStack protects your data, manages user accounts securely, and maintains privacy in your MCP server deployments. +--- + +# Security and Privacy + +DeployStack takes security seriously. This guide explains how we protect your information and what you can do to keep your account and deployments secure. + +## Your Account Security + +### Secure Passwords +DeployStack uses industry-standard security practices to protect your password: + +- **Never stored in plain text**: Your password is encrypted using advanced security methods +- **Unique protection**: Each password gets its own unique security key +- **Computational protection**: Even if someone accessed our database, your password would be extremely difficult to decrypt + +**What this means for you**: Your password is safe, but you should still choose a strong, unique password. + +### Login Sessions +When you log into DeployStack: + +- **Secure cookies**: Your login is stored in a secure cookie that websites can't access +- **Automatic expiration**: Sessions automatically expire after 30 days for security +- **HTTPS protection**: All login information is encrypted when traveling over the internet +- **Safe logout**: Logging out immediately invalidates your session + +**What this means for you**: You can trust that your login sessions are secure and protected. + +### Email Verification +To ensure account security: + +- **Verification required**: New accounts must verify their email address +- **Secure tokens**: Verification links contain secure, time-limited tokens +- **24-hour expiration**: Verification links expire after 24 hours +- **One-time use**: Each verification link can only be used once +- **Administrator exception**: The first user (administrator) is automatically verified + +**What this means for you**: Only you can activate your account, and verification links are secure and temporary. + +## Data Protection + +### Sensitive Settings +Your configuration data is protected with encryption: + +- **Encrypted storage**: Sensitive settings like passwords and API keys are encrypted +- **Secure keys**: Encryption uses industry-standard methods +- **Protected access**: Only authorized users can view or modify settings + +**What this means for you**: Your SMTP passwords, API keys, and other sensitive configuration data is securely encrypted. + +### Database Security +All data is protected through: + +- **Input validation**: Everything you enter is checked for security before being saved +- **SQL injection protection**: Database queries are automatically secured +- **Proper access controls**: Users can only access data they're authorized to see + +**What this means for you**: Your data is protected from common security attacks. + +## Account Access Control + +### User Roles +DeployStack uses role-based access to keep your installation secure: + +- **Administrator access**: Only administrators can manage users and system settings +- **User isolation**: Regular users can only access their own teams and projects +- **Permission checking**: Every action is checked against your current permissions + +**What this means for you**: Users only have access to features and data appropriate for their role. + +### Team Security +Your teams and projects are protected: + +- **Team ownership**: Only team owners can modify team settings +- **Member control**: Team access is controlled by the team owner +- **Isolated data**: Teams cannot access each other's information + +**What this means for you**: Your team data is private and secure from other users. + +## Privacy + +### What Information We Collect +DeployStack only collects information necessary for operation: + +- **Account information**: Username, email, name (what you provide during registration) +- **Team data**: Team names, descriptions, and membership +- **Deployment information**: Information about your MCP server deployments +- **System settings**: Configuration you set up for email, authentication, etc. + +### What We Don't Collect +- **Browsing behavior**: We don't track what you do outside DeployStack +- **Personal files**: We don't access files on your computer +- **Third-party data**: We don't collect data from other services unless you explicitly connect them + +### Data Retention +- **Active accounts**: Data is retained while your account is active +- **Deleted accounts**: When you delete your account, your data is removed +- **Backups**: System backups may retain data for operational purposes + +## Best Practices for Users + +### Strong Passwords +- Use a unique password for DeployStack +- Consider using a password manager +- Don't share your password with others +- Change your password if you suspect it's been compromised + +### Account Security +- Log out when using shared computers +- Don't share your account credentials +- Report suspicious activity to your administrator +- Keep your email account secure (used for password resets) + +### Team Management +- Only invite trusted users to your teams +- Review team membership regularly +- Use appropriate role assignments +- Remove users who no longer need access + +### Deployment Security +- Review MCP servers before deploying them +- Use trusted sources for MCP servers +- Keep deployment credentials secure +- Monitor your deployed services + +## Reporting Security Issues + +### If You Find a Security Problem +We appreciate responsible security reporting: + +1. **Don't share publicly**: Please don't post security issues on public forums +2. **Contact us directly**: Email security concerns to our team +3. **Provide details**: Include steps to reproduce the issue if possible +4. **Be patient**: We'll work with you to understand and fix the issue + +### What We'll Do +- **Acknowledge quickly**: We'll confirm receipt of your report +- **Investigate thoroughly**: We'll work to understand the issue +- **Fix promptly**: We'll develop and deploy fixes as quickly as possible +- **Keep you informed**: We'll update you on our progress + +## Getting Help + +### Security Questions +If you have questions about security: + +- **Account issues**: Contact your administrator +- **General security**: Visit our [Discord community](https://discord.gg/UjFWwByB) +- **Suspected problems**: Report them following the guidelines above + +### Password Problems +If you can't log in: + +- **Forgot password**: Use the "Forgot Password" link on the login page +- **Account locked**: Contact your administrator +- **Email issues**: Ensure you can receive emails at your registered address + +### Privacy Concerns +If you have privacy questions: + +- **Data access**: Contact your administrator to understand what data is stored +- **Data deletion**: Ask your administrator about account deletion procedures +- **Data export**: Inquire about getting a copy of your data + +## Security Updates + +DeployStack is regularly updated with security improvements: + +- **Automatic updates**: Security patches are applied promptly +- **Dependency updates**: We keep security libraries current +- **Regular reviews**: We continuously assess and improve security measures + +**What this means for you**: The security of DeployStack improves over time, and you benefit from ongoing security enhancements. + +## Summary + +DeployStack is designed with security as a core principle: + +- **Your passwords are strongly protected** with modern encryption +- **Your sessions are secure** and automatically protected +- **Your data is encrypted** when it needs to be +- **Access is controlled** based on roles and permissions +- **Privacy is respected** - we only collect what's necessary + +By following security best practices and understanding how DeployStack protects your information, you can use the platform confidently for your MCP server deployments. diff --git a/docs/index.mdx b/docs/index.mdx index a553c26..8266e46 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -1,83 +1,97 @@ --- title: DeployStack Documentation -description: Welcome to DeployStack documentation. Learn how to automate Docker Compose deployments across cloud providers with Infrastructure as Code templates and one-click deployments. +description: Welcome to DeployStack documentation. Learn how to deploy MCP servers to any cloud provider with one-click deployments, secure credential management, and team collaboration features. icon: CircleHelp --- -import { CloudUpload, Terminal, FileText, Container, BookOpenText, MessageCircleHeart } from 'lucide-react'; +import { CloudUpload, Rocket, LockKeyhole, Terminal, FileText, Container, BookOpenText, MessageCircleHeart } from 'lucide-react'; # DeployStack Documentation -DeployStack converts your **Docker configurations** into **Infrastructure as Code** (IaC) templates for multiple cloud providers. Whether you have a docker-compose.yml file or docker run commands, it generates the necessary AWS CloudFormation, Render.com Blueprint, DigitalOcean specifications, or Kubernetes Helm charts for example. This lets you and your users deploy the same application consistently across different cloud platforms using their native deployment mechanisms, **without needing to manually create** each provider's infrastructure. +DeployStack is the first **CI/CD platform specifically built for MCP servers**. Deploy Model Context Protocol servers to any cloud provider with one click, manage credentials securely, and collaborate with your team. Whether you're building MCP servers for Claude Desktop, VS Code, or other AI applications, DeployStack eliminates the deployment complexity that currently limits MCP adoption. ## Get Started -DeployStack simplifies cloud deployment through three key steps: configure your Docker setup, translate docker compose or run command to IaC templates, and enable one-click deployment for your users. Start by understanding the core concepts and how to integrate DeployStack with your repository. +DeployStack simplifies MCP server deployment through three key steps: browse our curated MCP server catalog, configure your credentials securely, and deploy to your preferred cloud provider instantly. Start by understanding the core concepts and how MCP servers integrate with AI applications. ### Core Concepts -} title="Quickstart" href="/deploystack/getting-started"> -Start with our Getting Started Guide to understand the basics of DeployStack. +} title="Quick-Start Guide" href="/deploystack/quick-start"> +Deploy Model Context Protocol (MCP) servers to selected cloud provider with a single click, eliminating the need for complex setup. -} title="One-Click Deploy" href="/deploystack/one-click-deploy"> -Learn how to enable One-Click Deploy buttons for your repository. +} title="MCP Server Catalog" href="https://deploystack.io/mcp"> +Browse our curated collection of ready-to-use MCP servers and deploy them instantly. -} title="Configuration" href="/deploystack/deploystack-configuration-directory"> -Configuration file placed to your repository, telling Zerops how to build and start your app. +} title="Security" href="/deploystack/security"> +Learn how to deploy MCP servers to selected cloud provider with secure credential management. + +} title="Team Management" href="/deploystack/team-collaboration"> +Manage MCP server deployments across your organization with role-based access control. -### Supported Cloud Providers +### MCP Server Categories -DeployStack generates infrastructure templates for major cloud providers, each optimized for their specific deployment patterns. AWS CloudFormation templates use Fargate for containerized workloads, DigitalOcean leverages App Platform, and Render.com implements Blueprints for smooth deployment. While translating your docker command to Infrastructure as Code by using [docker-to-iac](/docker-to-iac/index) module, you can choose your target provider. +Our catalog spans essential MCP server categories that connect AI agents to real-world systems and data sources: - -AWS +} title="Database Connectors" href="/deploystack/categories/databases"> +Connect AI agents to PostgreSQL, MySQL, MongoDB, and other database systems - -DigitalOcean +} title="API Integrations" href="/deploystack/categories/apis"> +Access REST APIs, GraphQL endpoints, and third-party services from AI applications - -Render.com +} title="File Systems" href="/deploystack/categories/filesystems"> +Enable AI agents to read, write, and manage files across local and cloud storage - -Helm +} title="Productivity Tools" href="/deploystack/categories/productivity"> +Integrate with Slack, GitHub, Jira, and other tools your team uses daily ### DeployStack Ecosystem -DeployStack consists of several integrated components that work together to enable consistent Docker to cloud deployment. Each repository serves a specific purpose in the ecosystem: +DeployStack consists of several integrated components that work together to enable comprehensive MCP server deployment and management: -} title="docker-to-iac" href="https://github.com/deploystackio/docker-to-iac"> -The core Node.js module that handles Docker configuration translation to Infrastructure as Code templates +} title="deploystack" href="https://github.com/deploystackio/deploystack"> +The main platform providing MCP server CI/CD, team collaboration, and multi-cloud deployment -} title="documentation" href="https://github.com/deploystackio/documentation"> -Central repository for all DeployStack documentation and guides +} title="awesome-mcp-server" href="https://github.com/deploystackio/awesome-mcp-server"> +Community-curated catalog of production-ready MCP servers with standardized configurations -} title="deploy-templates" href="https://github.com/deploystackio/deploy-templates"> -Houses all generated Infrastructure as Code templates for supported repositories +} title="documentation" href="https://github.com/deploystackio/documentation"> +Comprehensive guides for MCP server development, deployment, and integration } title="feedback" href="https://github.com/deploystackio/feedback"> Public repository for feature requests, bug reports, and roadmap discussions -## Contributing to DeployStack docker-to-iac module +## MCP Server Development + +### Creating MCP Servers -DeployStack is open source and we welcome contributions. Here's how you can help: +- Follow MCP specification standards for maximum compatibility +- Implement proper authentication and security practices +- Test across different transport protocols (stdio, HTTP, SSE) +- Document environment variables and configuration requirements -- Add support for new cloud providers -- Improve existing Infrastructure as Code templates -- Enhance documentation -- Report issues and suggest improvements +### Contributing to the Catalog -Visit our [GitHub repository](https://github.com/deploystackio/docker-to-iac) to get started. +- Submit your MCP server to [awesome-mcp-server](https://github.com/deploystackio/awesome-mcp-server) +- Follow our contribution guidelines for standardized formatting +- Include comprehensive documentation and usage examples +- Ensure production-ready deployment configurations + +Visit our [MCP Server Development Guide](/deploystack/mcp-development) for detailed instructions. ## Community and Support -- Join our [Discord community](https://discord.gg/UjFWwByB) -- Check our [troubleshooting guide](/deploystack/troubleshooting) +- Join our [Discord community](https://discord.gg/42Ce3S7b3b) for real-time discussions +- Explore the [MCP Server Catalog](https://deploystack.io/mcp) for deployment-ready servers +- Check our [troubleshooting guide](/deploystack/troubleshooting) for common issues +- Follow [@deploystack](https://twitter.com/deploystack) for ecosystem updates + +Ready to eliminate MCP server deployment complexity? [Get started for free →](https://cloud.deploystack.io) From f22ce13ca41729456e446b806ebab88a99507a4f Mon Sep 17 00:00:00 2001 From: Lasim Date: Sat, 21 Jun 2025 21:30:34 +0200 Subject: [PATCH 15/17] refactor: update layout configuration to use specific options for Home and Docs layouts --- .gitignore | 1 + app/[[...slug]]/page.tsx | 6 +++--- app/layout.config.tsx | 17 ++++++++++++----- 3 files changed, 16 insertions(+), 8 deletions(-) diff --git a/.gitignore b/.gitignore index 1f65420..1c0b88b 100644 --- a/.gitignore +++ b/.gitignore @@ -74,4 +74,5 @@ coverage/ ._*.md ._*.json ._*.ts +._*.tsx out/ diff --git a/app/[[...slug]]/page.tsx b/app/[[...slug]]/page.tsx index 6c2e668..e662a0d 100644 --- a/app/[[...slug]]/page.tsx +++ b/app/[[...slug]]/page.tsx @@ -8,7 +8,7 @@ import { generatePageMetadata, getCanonicalUrl } from '@/lib/seo-utils'; import { getFinalPageTitle } from '@/lib/h1-extractor'; import { readFile } from 'fs/promises'; import { getMDXComponents } from '@/mdx-components'; -import { baseOptions } from '../layout.config'; +import { homeOptions, docsOptions } from '../layout.config'; import { docs } from '@/.source/index'; export default async function Page({ @@ -31,7 +31,7 @@ export default async function Page({ // Use HomeLayout for root page (no sidebar), DocsLayout for all other pages if (isRootPage) { return ( - +
@@ -43,7 +43,7 @@ export default async function Page({ return ( Date: Sat, 21 Jun 2025 21:50:24 +0200 Subject: [PATCH 16/17] feat: enhance documentation structure by adding sidebar links and removing obsolete meta files --- .../deploystack/development/backend/index.mdx | 1 + .../deploystack/development/backend/meta.json | 4 - .../development/frontend/index.mdx | 1 + .../development/frontend/meta.json | 4 - docs/deploystack/index.mdx | 151 +++++++++++++++--- docs/deploystack/meta.json | 14 +- docs/index.mdx | 2 +- 7 files changed, 146 insertions(+), 31 deletions(-) delete mode 100644 docs/deploystack/development/backend/meta.json delete mode 100644 docs/deploystack/development/frontend/meta.json diff --git a/docs/deploystack/development/backend/index.mdx b/docs/deploystack/development/backend/index.mdx index 4ce2225..7bdf37d 100644 --- a/docs/deploystack/development/backend/index.mdx +++ b/docs/deploystack/development/backend/index.mdx @@ -1,6 +1,7 @@ --- title: Backend Development description: Complete guide to developing and contributing to the DeployStack backend - a high-performance Node.js application built with Fastify, TypeScript, and extensible plugin architecture. +sidebar: Getting Started --- import { Card, Cards } from 'fumadocs-ui/components/card'; diff --git a/docs/deploystack/development/backend/meta.json b/docs/deploystack/development/backend/meta.json deleted file mode 100644 index 9c11ef8..0000000 --- a/docs/deploystack/development/backend/meta.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "title": "Backend Development", - "description": "Complete guide to developing the DeployStack backend application" -} diff --git a/docs/deploystack/development/frontend/index.mdx b/docs/deploystack/development/frontend/index.mdx index 94e0694..fe80308 100644 --- a/docs/deploystack/development/frontend/index.mdx +++ b/docs/deploystack/development/frontend/index.mdx @@ -1,6 +1,7 @@ --- title: Frontend Development Guide description: Complete guide to developing and contributing to the DeployStack frontend application built with Vue 3, TypeScript, and Vite. +sidebar: Getting Started --- # DeployStack Frontend Development diff --git a/docs/deploystack/development/frontend/meta.json b/docs/deploystack/development/frontend/meta.json deleted file mode 100644 index adb4651..0000000 --- a/docs/deploystack/development/frontend/meta.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "title": "Frontend Development", - "description": "Complete guide to developing the DeployStack frontend application" -} diff --git a/docs/deploystack/index.mdx b/docs/deploystack/index.mdx index 5f677c0..5244b79 100644 --- a/docs/deploystack/index.mdx +++ b/docs/deploystack/index.mdx @@ -1,46 +1,155 @@ --- title: DeployStack Documentation description: Official DeployStack documentation - The first CI/CD platform designed for MCP servers. Deploy Model Context Protocol servers across cloud providers with one click. -menuTitle: DeployStack +sidebar: Introduction +icon: Star --- +import { Card, Cards } from 'fumadocs-ui/components/card'; +import { Rocket, Settings, Users, Code2, ExternalLink, Zap, Shield, Wrench } from 'lucide-react'; + # DeployStack - MCP Server CI/CD Platform DeployStack is the first CI/CD platform specifically designed for Model Context Protocol (MCP) servers. We make it easy to deploy and manage MCP servers across different cloud providers, transforming complex technical processes into one-click solutions. -## Quick Start - -**New to MCP servers?** Start here to understand how DeployStack simplifies MCP server deployment and management. - -- [Getting Started](/deploystack/getting-started) - Your first MCP server deployment -- [MCP Server Catalog](https://deploystack.io/mcp) - Browse ready-to-deploy MCP servers -- [One-Click Deploy](/deploystack/one-click-deploy) - Deploy any MCP server instantly + + {/* } + href="/deploystack/getting-started" + title="Getting Started" + > + Deploy your first MCP server in minutes with our step-by-step guide + */} + + } + href="https://deploystack.io/mcp" + title="MCP Server Catalog" + external + > + Browse ready-to-deploy MCP servers from the community + + + } + href="/deploystack/one-click-deploy" + title="One-Click Deploy" + > + Deploy any MCP server instantly with zero configuration + + ## User Guides **For administrators and team members** using DeployStack: -- [Global Settings](/deploystack/global-settings) - Configure email, authentication, and system preferences -- [User Roles and Permissions](/deploystack/roles) - Manage user access and team collaboration -- [Troubleshooting](/deploystack/troubleshooting) - Resolve common deployment issues + + } + href="/deploystack/global-settings" + title="Global Settings" + > + Configure email, authentication, and system preferences + + + } + href="/deploystack/roles" + title="User Roles and Permissions" + > + Manage user access and team collaboration + + + {/* } + href="/deploystack/troubleshooting" + title="Troubleshooting" + > + Resolve common deployment issues and get help + */} + ## MCP Server Requirements **For MCP server creators** who want to make their servers deployable: -- [Docker Compose Requirements](/deploystack/docker-compose-requirements) - Learn about supported configurations -- [Submit Your MCP Server](https://deploystack.io/submit) - Add your server to our catalog + + } + href="/deploystack/docker-compose-requirements" + title="Docker Compose Requirements" + > + Learn about supported configurations and best practices + + + } + href="https://deploystack.io/submit" + title="Submit Your MCP Server" + external + > + Add your server to our catalog for the community + + ## Developer Documentation **For developers** extending or contributing to DeployStack: -- [Backend Development](/deploystack/development/backend) - API, database, plugins, and testing -- [Docker-to-IaC Module](/docker-to-iac/index) - Core deployment engine documentation - -## Additional Resources - -- [Join our Discord](https://discord.gg/UjFWwByB) - Get help and connect with the community -- [Visit DeployStack](https://deploystack.io) - Main website and MCP server catalog -- [GitHub Repository](https://github.com/deploystackio/deploystack) - Contribute to the project + + } + href="/deploystack/development" + title="Development Guide" + > + Complete development documentation for frontend and backend + + + } + href="/deploystack/development/backend" + title="Backend Development" + > + API, database, plugins, and testing documentation + + + } + href="/docker-to-iac/index" + title="Docker-to-IaC Module" + > + Core deployment engine and infrastructure automation + + + +## Community & Resources + + + } + href="https://discord.gg/UjFWwByB" + title="Join our Discord" + external + > + Get help and connect with the DeployStack community + + + } + href="https://deploystack.io" + title="Visit DeployStack" + external + > + Main website and MCP server catalog + + + } + href="https://github.com/deploystackio/deploystack" + title="GitHub Repository" + external + > + Contribute to the project and view source code + + diff --git a/docs/deploystack/meta.json b/docs/deploystack/meta.json index 87ea42c..6807cea 100644 --- a/docs/deploystack/meta.json +++ b/docs/deploystack/meta.json @@ -4,6 +4,18 @@ "icon": "DeployStackLogo", "root": true, "pages": [ - "..." + "index.mdx", + "---General---", + "global-settings.mdx", + "roles.mdx", + "security.mdx", + "---Development---", + "development/index.mdx", + "---Frontend Development---", + "development/frontend/index.mdx", + "...development/frontend", + "---Backend Development---", + "development/backend/index.mdx", + "...development/backend" ] } diff --git a/docs/index.mdx b/docs/index.mdx index 8266e46..479672f 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -17,7 +17,7 @@ DeployStack simplifies MCP server deployment through three key steps: browse our ### Core Concepts -} title="Quick-Start Guide" href="/deploystack/quick-start"> +} title="Quick-Start Guide" href="/deploystack"> Deploy Model Context Protocol (MCP) servers to selected cloud provider with a single click, eliminating the need for complex setup. } title="MCP Server Catalog" href="https://deploystack.io/mcp"> From b03c29d81e2862e4d13dbae702864c14703d2c9b Mon Sep 17 00:00:00 2001 From: Lasim Date: Sat, 21 Jun 2025 22:19:57 +0200 Subject: [PATCH 17/17] fix: update links in documentation for global settings and security details to use correct paths --- docs/deploystack/development/backend/global-settings.mdx | 4 ++-- docs/deploystack/development/backend/mail.mdx | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/deploystack/development/backend/global-settings.mdx b/docs/deploystack/development/backend/global-settings.mdx index 550c0ef..7524e75 100644 --- a/docs/deploystack/development/backend/global-settings.mdx +++ b/docs/deploystack/development/backend/global-settings.mdx @@ -1018,5 +1018,5 @@ if (await GlobalSettings.isSet('api.key')) { --- -For more information about the role-based access control system, see [ROLES.md](ROLES.md). -For security details, see [SECURITY.md](SECURITY.md). +For more information about the role-based access control system, see [ROLES](/deploystack/development/backend/roles). +For security details, see [SECURITY](/deploystack/development/backend/security). diff --git a/docs/deploystack/development/backend/mail.mdx b/docs/deploystack/development/backend/mail.mdx index 8a454c4..037c7fd 100644 --- a/docs/deploystack/development/backend/mail.mdx +++ b/docs/deploystack/development/backend/mail.mdx @@ -642,4 +642,4 @@ const emailResult = await EmailService.sendEmail({...}); --- -For more information about global settings configuration, see [GLOBAL_SETTINGS.md](GLOBAL_SETTINGS.md). +For more information about global settings configuration, see [GLOBAL_SETTINGS](/deploystack/development/backend/global-settings).