Hello, stackql-deploy on AWS!
Hello, stackql-deploy on AWS!
+
+ Hello, stackql-deploy on Azure!
+ + + +[**PyPi**][pypi] +[**Raise an Issue**][issues] + +
+Hello, stackql-deploy on AWS!
+
+ Hello, stackql-deploy on Azure!
stackql-deploy build STACK_DIR STACK_ENV [FLAGS]
+
+* * *
+
+## Arguments
+
+| Argument | Description | Example |
+|--|--|--|
+|`STACK_DIR`|The directory containing the stack configuration files | `my-stack` |
+|`STACK_ENV`|The target environment for the stack deployment | `dev` |
+
+:::info
+
+`STACK_DIR` can be an absolute or relative path.
+
+`STACK_ENV` is a user defined environment symbol (e.g. `dev`, `sit`, `prd`) which is used to deploy your stack to different environments.
+
+:::
+
+## Optional Flags
+
+| Flag | Description | Example |
+|--|--|--|
+|`--log-level`|Set the logging level. Default is `INFO` | `--log-level DEBUG` |
+|`--env-file`|Specify an environment variables file. Default is `.env` | `--env-file .env` |
+|`-e` `--env`|Set additional environment variables (can be used multiple times) | `--env DB_USER=admin` |
+|`--dry-run`|Perform a dry run of the operation. No changes will be made | |
+|`--show-queries`|Display the queries executed in the output logs | |
+|`--output-file`|Export deployment variables to a JSON file after successful deployment | `--output-file ./outputs/deploy.json` |
+|`--download-dir`|Custom download directory for StackQL | `/etc/stackql` |
+|`--custom-registry`|Custom StackQL provider registry URL | `https://myreg` |
+
+:::tip
+
+Exported variables specified as `protected` in the respective resource definition in the `stackql_manifest.yml` file are obfuscated in the logs by default.
+
+:::
+
+* * *
+
+## Examples
+
+### Deploy a stack to a target environment
+
+Deploy the stack defined in the `azure-stack` directory to the `sit` environment, setting additional environment variables to be used in the deployment:
+
+```bash
+stackql-deploy build azure-stack sit \
+-e AZURE_SUBSCRIPTION_ID=631d1c6d-0000-0000-0000-688bfe4e1468
+```
+
+### Perform a dry run deployment
+
+Perform a dry run or a stack defined in the `aws-stack` directory to a `prd` environment, showing templated queries without actually running them:
+
+```bash
+stackql-deploy build aws-stack prd \
+--dry-run
+```
+
+### Specifying a custom environment file
+
+Use a custom environment file `.env.prod` to supply environment variables to a stack defined in the `gcp-stack` directory to a `prod` environment:
+
+```bash
+stackql build gcp-stack prod \
+--env-file .env.prod
+```
+
+### Export deployment variables to a file
+
+Deploy a stack and export key deployment variables to a JSON file for use in CI/CD workflows or downstream processes:
+
+```bash
+stackql-deploy build databricks-stack prod \
+--output-file ./outputs/deployment.json \
+-e DATABRICKS_ACCOUNT_ID=12345678-1234-1234-1234-123456789012
+```
+
+This will create a JSON file containing the exported variables defined in the `exports` section of your `stackql_manifest.yml`:
+
+```json
+{
+ "stack_name": "my-databricks-workspace",
+ "stack_env": "prod",
+ "workspace_name": "my-databricks-workspace-prod",
+ "workspace_id": "123456789012345",
+ "deployment_name": "dbc-ab123456-789a",
+ "workspace_status": "RUNNING"
+}
+```
+
+:::tip
+
+`stack_name` and `stack_env` are automatically included in all exports and do not need to be listed in the manifest.
+
+:::
diff --git a/ref-python-packages/stackql-deploy/website/docs/cli-reference/info.md b/ref-python-packages/stackql-deploy/website/docs/cli-reference/info.md
new file mode 100644
index 0000000..0b2978b
--- /dev/null
+++ b/ref-python-packages/stackql-deploy/website/docs/cli-reference/info.md
@@ -0,0 +1,84 @@
+---
+title: info
+hide_title: true
+hide_table_of_contents: false
+keywords:
+ - stackql
+ - stackql-deploy
+ - infrastructure-as-code
+ - configuration-as-data
+tags:
+ - stackql
+ - stackql-deploy
+ - infrastructure-as-code
+ - configuration-as-data
+description: Documentation for the info command in StackQL Deploy
+image: "/img/stackql-cover.png"
+---
+
+# `info`
+
+Command used to display version information and environment details for the StackQL Deploy program and its dependencies.
+
+* * *
+
+## Syntax
+
+stackql-deploy info [FLAGS]
+
+* * *
+
+## Optional Flags
+
+| Flag | Description | Example |
+|--|--|--|
+| `--download-dir` | Custom download directory for StackQL | `/etc/stackql` |
+| `--custom-registry` | Custom StackQL provider registry URL | `https://myreg` |
+
+* * *
+
+## Description
+
+The `info` command provides detailed information about the StackQL Deploy environment, including the versions of `stackql-deploy`, `pystackql`, and the `stackql` binary, as well as the paths and platform information. If a custom provider registry is used, that information will also be displayed. Additionally, the command lists all installed providers and their versions.
+
+## Examples
+
+### Display version information
+
+Display the version information of the `stackql-deploy` tool, its dependencies, and the installed providers:
+
+```bash
+stackql-deploy info
+```
+outputs...
+
+```plaintext
+stackql-deploy version: 1.6.1
+pystackql version : 3.6.4
+stackql version : v0.5.708
+stackql binary path : /home/javen/.local/stackql
+platform : Linux x86_64 (Linux-5.15.133.1-microsoft-standard-WSL2-x86_64-with-glibc2.35), Python 3.10.12
+
+installed providers: :
+aws : v24.07.00246
+azure : v24.06.00242
+google : v24.06.00236
+```
+
+### Specify a custom `stackql` binary location
+
+`stackql-deploy` will automatically download the `stackql` binary when a command is run, if the binary does not exist in the default directory. Alternatively, you can supply the `--download-dir` flag to specify the location of an existing `stackql` binary, or have `stackql-deploy` download the `stackql` binary to this location.
+
+```bash
+stackql-deploy info \
+--download-dir /usr/local/bin/stackql
+```
+
+### Specify a custom provider registry URL
+
+By default the public [StackQL Provider Registry](https://github.com/stackql/stackql-provider-registry) is used for provider definitions, to supply custom providers or use an alternate registry, specify the custom regsitry URL using the `--custom-registry` flag. The following example will use the public StackQL dev provider registry.
+
+```bash
+stackql-deploy info \
+--custom-registry="https://registry-dev.stackql.app/providers"
+```
diff --git a/ref-python-packages/stackql-deploy/website/docs/cli-reference/init.md b/ref-python-packages/stackql-deploy/website/docs/cli-reference/init.md
new file mode 100644
index 0000000..b3b58d7
--- /dev/null
+++ b/ref-python-packages/stackql-deploy/website/docs/cli-reference/init.md
@@ -0,0 +1,82 @@
+---
+title: init
+hide_title: true
+hide_table_of_contents: false
+keywords:
+ - stackql
+ - stackql-deploy
+ - infrastructure-as-code
+ - configuration-as-data
+tags:
+ - stackql
+ - stackql-deploy
+ - infrastructure-as-code
+ - configuration-as-data
+description: Documentation for the init command in StackQL Deploy
+image: "/img/stackql-cover.png"
+---
+
+# `init`
+
+Command used to initialize a new `stackql-deploy` project structure.
+
+* * *
+
+## Syntax
+
+stackql-deploy init STACK_DIR [FLAGS]
+
+* * *
+
+## Arguments
+
+| Argument | Description | Example |
+|--|--|--|
+| `STACK_DIR` | The directory (and name) for the project to be created | `my-stack` |
+
+## Optional Flags
+
+| Flag | Description | Example |
+|--|--|--|
+| `--provider` | Specify a cloud provider to start your project with. Supported values: `aws`, `azure`, `google`. Default is `azure`. | `--provider aws` |
+
+* * *
+
+## Description
+
+The `init` command sets up a new project structure for a `stackql-deploy` stack. It creates the necessary directories and populates them with template files tailored to the specified cloud provider.
+
+- If no provider is specified, the default provider is `azure`.
+- The command ensures that the project name is converted to a lower-case, hyphen-separated format.
+- The command also generates provider-specific example templates within the `resources` directory.
+
+Supported providers include:
+
+- **AWS**: Creates a sample VPC resource.
+- **Azure**: Creates a sample Resource Group.
+- **Google Cloud**: Creates a sample VPC resource.
+
+If a provider is not supported, the command will default to `azure` and notify the user.
+
+## Examples
+
+### Initialize a new project with default provider
+
+This command initializes a new project with the name `my-stack` using the default provider (`azure`):
+
+```bash
+stackql-deploy init my-stack
+```
+:::tip
+
+`init` will create your project structure including the stack directory including the `stackql_manifest.yml` and `README.md` files, and a `resources` directory with a sample StackQL resource query file (`.iql` file). You can modify a project to use whichever providers are available in the [StackQL Provider Registry](https://stackql.io/providers).
+
+:::
+
+### Initialize a new project with the `aws` provider
+
+Initialize a new project with the name `my-aws-stack` using `aws` as the provider:
+
+```bash
+stackql-deploy init my-aws-stack --provider aws
+```
diff --git a/ref-python-packages/stackql-deploy/website/docs/cli-reference/shell.md b/ref-python-packages/stackql-deploy/website/docs/cli-reference/shell.md
new file mode 100644
index 0000000..4e4984b
--- /dev/null
+++ b/ref-python-packages/stackql-deploy/website/docs/cli-reference/shell.md
@@ -0,0 +1,70 @@
+---
+title: shell
+hide_title: true
+hide_table_of_contents: false
+keywords:
+ - stackql
+ - stackql-deploy
+ - infrastructure-as-code
+ - configuration-as-data
+tags:
+ - stackql
+ - stackql-deploy
+ - infrastructure-as-code
+ - configuration-as-data
+description: Documentation for the shell command in StackQL Deploy
+image: "/img/stackql-cover.png"
+---
+
+# `shell`
+
+Command used to launch the StackQL interactive shell.
+
+* * *
+
+## Syntax
+
+stackql-deploy shell [FLAGS]
+
+* * *
+
+## Optional Flags
+
+| Flag | Description | Example |
+|--|--|--|
+|`--download-dir`|Custom download directory for StackQL | `/etc/stackql` |
+|`--custom-registry`|Custom StackQL provider registry URL | `https://myreg` |
+
+:::info
+
+The `shell` command launches the interactive StackQL shell. If the `stackql` binary is not found in the provided paths, the command will fail with an error.
+
+:::
+
+* * *
+
+## Examples
+
+### Launch the StackQL shell using the default binary location
+
+This command attempts to launch the StackQL shell using the binary location managed by the `pystackql` package:
+
+```bash
+stackql-deploy shell
+```
+
+### Launch the StackQL shell from a custom download directory
+
+Specify a custom directory where the `stackql` binary is downloaded and run the StackQL shell:
+
+```bash
+stackql-deploy shell --download-dir /usr/local/bin/stackql
+```
+
+### Use a custom registry URL
+
+Launch the StackQL shell using a custom StackQL provider registry:
+
+```bash
+stackql-deploy shell --custom-registry https://mycustomregistry.com
+```
diff --git a/ref-python-packages/stackql-deploy/website/docs/cli-reference/teardown.md b/ref-python-packages/stackql-deploy/website/docs/cli-reference/teardown.md
new file mode 100644
index 0000000..4332f97
--- /dev/null
+++ b/ref-python-packages/stackql-deploy/website/docs/cli-reference/teardown.md
@@ -0,0 +1,75 @@
+---
+title: teardown
+hide_title: true
+hide_table_of_contents: false
+keywords:
+ - stackql
+ - stackql-deploy
+ - infrastructure-as-code
+ - configuration-as-data
+tags:
+ - stackql
+ - stackql-deploy
+ - infrastructure-as-code
+ - configuration-as-data
+description: Documentation for the teardown command in StackQL Deploy
+image: "/img/stackql-cover.png"
+---
+
+# `teardown`
+
+Command used to deprovision and remove resources in a specified stack in a given environment.
+
+* * *
+
+## Syntax
+
+stackql-deploy teardown STACK_DIR STACK_ENV [FLAGS]
+
+* * *
+
+## Arguments
+
+| Argument | Description | Example |
+|--|--|--|
+| `STACK_DIR` | The directory containing the stack configuration files | `my-stack` |
+| `STACK_ENV` | The target environment for tearing down the stack | `dev` |
+
+:::info
+
+`STACK_DIR` can be an absolute or relative path.
+
+`STACK_ENV` is a user-defined environment symbol (e.g., `dev`, `sit`, `prd`) used to tear down your stack in different environments.
+
+:::
+
+## Optional Flags
+
+| Flag | Description | Example |
+|--|--|--|
+| `--log-level` | Set the logging level. Default is `INFO` | `--log-level DEBUG` |
+| `--env-file` | Specify an environment variables file. Default is `.env` | `--env-file .env` |
+| `-e` `--env` | Set additional environment variables (can be used multiple times) | `--env DB_USER=admin` |
+| `--dry-run` | Perform a dry run of the operation. No changes will be made | |
+| `--show-queries` | Display the queries executed in the output logs | |
+| `--download-dir`|Custom download directory for StackQL | `/etc/stackql` |
+| `--custom-registry`|Custom StackQL provider registry URL | `https://myreg` |
+
+:::tip
+
+Exported variables specified as `protected` in the respective resource definition in the `stackql_manifest.yml` file are obfuscated in the logs by default.
+
+:::
+
+* * *
+
+## Examples
+
+### Teardown a stack in a target environment
+
+Teardown the stack defined in the `azure-stack` directory in the `sit` environment, setting additional environment variables:
+
+```bash
+stackql-deploy teardown azure-stack sit \
+-e AZURE_SUBSCRIPTION_ID=631d1c6d-0000-0000-0000-688bfe4e1468
+```
diff --git a/ref-python-packages/stackql-deploy/website/docs/cli-reference/test.md b/ref-python-packages/stackql-deploy/website/docs/cli-reference/test.md
new file mode 100644
index 0000000..63db135
--- /dev/null
+++ b/ref-python-packages/stackql-deploy/website/docs/cli-reference/test.md
@@ -0,0 +1,76 @@
+---
+title: test
+hide_title: true
+hide_table_of_contents: false
+keywords:
+ - stackql
+ - stackql-deploy
+ - infrastructure-as-code
+ - configuration-as-data
+tags:
+ - stackql
+ - stackql-deploy
+ - infrastructure-as-code
+ - configuration-as-data
+description: Documentation for the test command in StackQL Deploy
+image: "/img/stackql-cover.png"
+---
+
+# `test`
+
+Command used to confirm the desired state of resources in a specified stack in a given environment.
+
+* * *
+
+## Syntax
+
+stackql-deploy test STACK_DIR STACK_ENV [FLAGS]
+
+* * *
+
+## Arguments
+
+| Argument | Description | Example |
+|--|--|--|
+| `STACK_DIR` | The directory containing the stack configuration files | `my-stack` |
+| `STACK_ENV` | The target environment for testing the stack | `dev` |
+
+:::info
+
+`STACK_DIR` can be an absolute or relative path.
+
+`STACK_ENV` is a user-defined environment symbol (e.g., `dev`, `sit`, `prd`) used to test your stack in different environments.
+
+:::
+
+## Optional Flags
+
+| Flag | Description | Example |
+|--|--|--|
+| `--log-level` | Set the logging level. Default is `INFO` | `--log-level DEBUG` |
+| `--env-file` | Specify an environment variables file. Default is `.env` | `--env-file .env` |
+| `-e` `--env` | Set additional environment variables (can be used multiple times) | `--env DB_USER=admin` |
+| `--dry-run` | Perform a dry run of the operation. No changes will be made | |
+| `--show-queries` | Display the queries executed in the output logs | |
+| `--download-dir`|Custom download directory for StackQL | `/etc/stackql` |
+| `--custom-registry`|Custom StackQL provider registry URL | `https://myreg` |
+
+:::tip
+
+Exported variables specified as `protected` in the respective resource definition in the `stackql_manifest.yml` file are obfuscated in the logs by default.
+
+:::
+
+* * *
+
+## Examples
+
+### Confirm desired state for a stack in a target environment
+
+Run tests for the stack defined in the `azure-stack` directory in the `sit` environment, setting additional environment variables:
+
+```bash
+stackql-deploy test azure-stack sit \
+-e AZURE_SUBSCRIPTION_ID=631d1c6d-0000-0000-0000-688bfe4e1468
+```
+
diff --git a/ref-python-packages/stackql-deploy/website/docs/cli-reference/upgrade.md b/ref-python-packages/stackql-deploy/website/docs/cli-reference/upgrade.md
new file mode 100644
index 0000000..5d95ad2
--- /dev/null
+++ b/ref-python-packages/stackql-deploy/website/docs/cli-reference/upgrade.md
@@ -0,0 +1,57 @@
+---
+title: upgrade
+hide_title: true
+hide_table_of_contents: false
+keywords:
+ - stackql
+ - stackql-deploy
+ - infrastructure-as-code
+ - configuration-as-data
+tags:
+ - stackql
+ - stackql-deploy
+ - infrastructure-as-code
+ - configuration-as-data
+description: Documentation for the upgrade command in StackQL Deploy
+image: "/img/stackql-cover.png"
+---
+
+# `upgrade`
+
+Command used to upgrade the `pystackql` package and `stackql` binary to the latest versions.
+
+* * *
+
+## Syntax
+
+stackql-deploy upgrade
+
+* * *
+
+## Description
+
+The `upgrade` command automates the process of upgrading both the `pystackql` package and the `stackql` binary to their latest available versions. This ensures that your environment is up-to-date with the latest features, improvements, and security patches.
+
+When the `upgrade` command is run, it first attempts to upgrade the `pystackql` package using `pip`. After that, it upgrades the `stackql` binary to the latest version.
+
+## Examples
+
+### Upgrade `pystackql` and `stackql` to the latest versions
+
+This command will upgrade both the `pystackql` package and the `stackql` binary:
+
+```bash
+stackql-deploy upgrade
+```
+
+outputs...
+
+```plaintext
+upgrading pystackql package...
+pystackql package upgraded successfully.
+pystackql package upgraded from 3.6.4 to 3.7.0.
+upgrading stackql binary, current version v0.5.708...
+stackql binary upgraded to v0.6.002.
+```
+
+If the `pystackql` package or the `stackql` binary is already up-to-date, the command will notify you accordingly.
diff --git a/ref-python-packages/stackql-deploy/website/docs/getting-started.md b/ref-python-packages/stackql-deploy/website/docs/getting-started.md
new file mode 100644
index 0000000..6299e1a
--- /dev/null
+++ b/ref-python-packages/stackql-deploy/website/docs/getting-started.md
@@ -0,0 +1,185 @@
+---
+id: getting-started
+title: Getting Started
+hide_title: false
+hide_table_of_contents: false
+description: A quick overview of how to get started with StackQL Deploy, including basic concepts and the essential components of a deployment.
+tags: []
+draft: false
+unlisted: false
+---
+
+import File from '/src/components/File';
+
+`stackql-deploy` is a model driven, declarative framework for provisioning, de-provisioning and testing cloud resources. Heard enough and ready to get started? Jump to a [__Quick Start__](#quick-start).
+
+## Installing `stackql-deploy`
+
+Installing `stackql-deploy` globally is as easy as...
+
+```bash
+pip install stackql-deploy
+# or
+pip3 install stackql-deploy
+```
+this will setup `stackql-deploy` and all its dependencies.
+
+> __Note for macOS users__
+> to install `stackql-deploy` in a virtual environment (which may be necessary on __macOS__), use the following:
+> ```bash
+> python3 -m venv myenv
+> source myenv/bin/activate
+> pip install stackql-deploy
+> ```
+
+## How `stackql-deploy` works
+
+The core components of `stackql-deploy` are the __stack directory__, the `stackql_manifest.yml` file and resource query (`.iql`) files. These files define your infrastructure and guide the deployment process.
+
+`stackql-deploy` uses the `stackql_manifest.yml` file in the `stack-dir`, to render query templates (`.iql` files) in the `resources` sub directory of the `stack-dir`, targeting an environment (`stack-env`). `stackql` is used to execute the queries to deploy, test, update or delete resources as directed. This is summarized in the diagram below:
+
+```mermaid
+flowchart LR
+ subgraph stack-dir
+ direction LR
+ B(Manifest File) --> C(Resource Files)
+ end
+
+ A(stackql-deploy) -->|uses...|stack-dir
+ stack-dir -->|deploys to...|D(āļø Your Environment)
+```
+
+### `stackql_manifest.yml` File
+
+The `stackql_manifest.yml` file is the basis of your stack configuration. It contains the definitions of the resources you want to manage, the providers you're using (such as AWS, Google Cloud, or Azure), and the environment-specific settings that will guide the deployment.
+
+This manifest file acts as a blueprint for your infrastructure, describing the resources and how they should be configured. An example `stackql_manifest.yml` file is shown here:
+
+
+stackql_manifest.yml fileHello, stackql-deploy on AWS!
+stackql_manifest.yml filestackql_manifest.yml filedocs directory.
+
+ ),
+ },
+ {
+ title: 'Powered by React',
+ Svg: require('@site/static/img/undraw_docusaurus_react.svg').default,
+ description: (
+ <>
+ Extend or customize your website layout by reusing React. Docusaurus can
+ be extended while reusing the same header and footer.
+
+ ),
+ },
+];
+
+function Feature({Svg, title, description}) {
+ return (
+ {description}
+| Type | +{type} |
+
| Required | +{required ? 'Yes' : 'No'} | +
| Fields | +
+ {fields.map((field, index) => (
+
+
+ {field.name}
+
+ {index < fields.length - 1 && ', '}
+
+ ))}
+ |
+
+ {finalDescription} +
+ )} +