| Name | open-dash JSON |
| Version |
0.1.0
JSON |
| download |
| home_page | None |
| Summary | Open Dash packages Plotly dash applications for deployment to AWS S3 and Lambda. Developed by Zonké. |
| upload_time | 2025-01-08 21:28:11 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | None |
| keywords |
dash
deployment
serverless
zonke
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# OpenDash
OpenDash prepares a [Plotly Dash](https://github.com/plotly/dash) application into artifacts that can be deployed to AWS. A Dash application is a Flask application that uses Plotly.js and React.js to create interactive web visualizations. OpenDash's core functionality extracts static assets from Dash's internal Flask server and prepares them for deployment to S3.
## Features
The output folder structure is similar to OpenNext's folder structure. The main artifacts are:
1. `.open-dash/static` - A static artifact that can be deployed to an S3 bucket. Assets include an `index.html` file that can be used as the CloudFront default root object. Assets are fingerprinted for cache invalidation.
2. `.open-dash/server-functions/default` - A Lambda artifact that contains the Dash application, an index.py file, and a Dockerfile. This is a fallback server in case your Dash application is not a SPA. Most usecases will not trigger the deployed lambda function.
3. `.open-dash/warmer-function` - Contains a handler that can be used to ping the Dash server lambda to keep it warm.
4. `.open-dash/data` - Contains the data directory from the source code. This directory can be used to store data files that are used by the Dash application (see [Data Triggered Deployments](https://docs.zonke.dev/architectures/dash/static#data-triggered-deployments)).
## Getting Started
### Preparing Your Dash Application
Define a `create_app` function in `app.py` that returns a Dash app instance.
```python
from dash import Dash
def create_app():
app = Dash(__name__)
app.layout = html.Div("Hello, World!") # Do your magic here...
return app
```
If you want the ability to run your Dash application locally, you can add the following code to the bottom of your `app.py` file.
```python
# Make sure to set the DEBUG and PORT environment variables.
if __name__ == "__main__" and os.getenv('DEBUG') == 'True':
create_app().run_server(debug=True, port=os.getenv('PORT', 8050))
```
### Configuring OpenDash
Create an `open-dash.config.json` file in the root of your project. The configuration file should contain the following fields:
```json
{
"warmer": true, // Optional - Whether to include a warmer function in the output bundle.
"export-static": true, // Optional - Whether to include an index.html and other static files in the output bundle.
"data-path": "path/to/data", // Optional - The path to the data directory.
"venv-path": "path/to/venv", // Optional - The path to the virtual environment. If not provided, the system Python interpreter is used.
"excluded-directories": ["__pycache__", ".git"], // Optional - Directories to exclude from the output bundle.
"domain-name": "example.com", // Optional - The domain name of the deployed application.
"target-base-path": "path/to/target", // Optional - The path to the target directory. If not provided, the source path's parent folder is used.
"source-path": "path/to/source", // Optional - The path to the source directory. If not provided, the current working directory is used.
"fingerprint": {
"version": true, // Whether to include the system package version in the fingerprint.
"method": "last-modified" // The method to use for fingerprinting. Options: "none", "global", "last-modified"
}
}
```
If you do not provide a configuration file, OpenDash will use the default configuration:
```json
{
"warmer": true,
"source-path": ".",
"export-static": true,
"target-base-path": "..",
"excluded-directories": [],
"fingerprint": {
"version": true,
"method": "last-modified"
}
}
```
### Generating Artifacts
Run the following commands to generate the artifacts.
```bash
python -m pip install open-dash
# NOTE: Run the next command in virtual environment because open-dash installs your application's dependencies.
# --config-path -> Path to the configuration file. If not provided, the fallback will be an open-dash.config.json file in the current directory, or a default configuration if neither is found.
open-dash bundle --config-path path/to/open-dash.config.json
# The output .open-dash folder will be a sibling of the source folder.
```
## File Fingerprinting
Dash fingerprints JS and CSS files to help with cache invalidation. The fingerprint is generated based on each file's
last modified time. This fingerprint approach works if assets are fetched from the same server. However, if you deploy
your assets to S3 and your server to Lambda, the fingerprint will be different for each. To give devs flexibility,
OpenDash supports multiple fingerprinting approaches:
1. **Last Modified Time** - The last modified time is used to generate the fingerprint if the index.html file is
generated at the same time as the static assets. This is the default fingerprinting method used by Dash.
2. **Global Fingerprint** - The fingerprint is generated based on the build time of the assets. This is ideal if you
are going to serve assets from S3, the index page from Lambda, and override the fingerprints returned by the index.html.
## Suggested Architecture (Not Included in OpenDash)
1. **CloudFront** - Serves static assets from the S3 bucket and falls back to the Dash server lambda for other requests. Remember to set the default root object to `index.html`.
2. **S3 Bucket** - Stores the static assets. Make sure to block public access and give CloudFront read access to the bucket. See this [AWS Guide](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/private-content-restricting-access-to-s3.html) for more information.
Optional infrastructure, depending on your application:
3. **Lambda@Edge Origin Request Function** - A Lambda function triggered by CloudFront to sign the Dash server lambda requests and configure headers.
4. **Dash Server Lambda** - A Lambda function that runs the Dash server. This function is triggered by CloudFront when the requested path does not match a static asset. Make sure you define the `DOMAIN_NAME` environment variable.
> NOTE: It is possible for the server lambda to not get called if your application is a SPA without a backend. Monitor your function's logs and adjust your architecture accordingly.
5. **Warmer Function** - A Lambda function that pings the Dash server lambda to keep it warm. This function is triggered by the EventBridge CRON.
6. **EventBridge CRON** - A CloudWatch event that triggers the warmer function every 5 minutes.
## Zero-Config Deployments
You can deploy your Dash application to AWS using the [Zonké dashboard](https://zonke.dev). The dashboard offers the following features:
1. **Zero-Config** - Deploy your Dash application to AWS without any configuration.
2. **Continuous Deployment** - Automatically deploy your Dash application when you push to your Git repository.
3. **Other Deployment Options** - Deploy your Dash application to other configurations, such as ECS Fargate/EC2.
## Acknowledgments
OpenDash was heavily inspired by, but not affiliated with, [OpenNext](https://github.com/opennextjs/opennextjs-aws).
---
Maintained by the [Zonké team](https://zonke.dev) | [Discord](https://discord.gg/CRNPV8BkjC) | [Twitter](https://x.com/ZonkeInc) | [LinkedIn](https://www.linkedin.com/company/zonke-inc)
Raw data
{
"_id": null,
"home_page": null,
"name": "open-dash",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "dash, deployment, serverless, zonke",
"author": null,
"author_email": "\"Zonk\u00e9, Inc.\" <support@zonke.dev>",
"download_url": "https://files.pythonhosted.org/packages/29/e0/18a168b252f4c5cccf119a1385ebe9458f5f70b0ae1d7544dce8e7807fc1/open_dash-0.1.0.tar.gz",
"platform": null,
"description": "# OpenDash\nOpenDash prepares a [Plotly Dash](https://github.com/plotly/dash) application into artifacts that can be deployed to AWS. A Dash application is a Flask application that uses Plotly.js and React.js to create interactive web visualizations. OpenDash's core functionality extracts static assets from Dash's internal Flask server and prepares them for deployment to S3.\n\n## Features\nThe output folder structure is similar to OpenNext's folder structure. The main artifacts are:\n1. `.open-dash/static` - A static artifact that can be deployed to an S3 bucket. Assets include an `index.html` file that can be used as the CloudFront default root object. Assets are fingerprinted for cache invalidation.\n2. `.open-dash/server-functions/default` - A Lambda artifact that contains the Dash application, an index.py file, and a Dockerfile. This is a fallback server in case your Dash application is not a SPA. Most usecases will not trigger the deployed lambda function.\n3. `.open-dash/warmer-function` - Contains a handler that can be used to ping the Dash server lambda to keep it warm.\n4. `.open-dash/data` - Contains the data directory from the source code. This directory can be used to store data files that are used by the Dash application (see [Data Triggered Deployments](https://docs.zonke.dev/architectures/dash/static#data-triggered-deployments)).\n\n## Getting Started\n### Preparing Your Dash Application\nDefine a `create_app` function in `app.py` that returns a Dash app instance.\n\n```python\nfrom dash import Dash\n\ndef create_app():\n app = Dash(__name__)\n app.layout = html.Div(\"Hello, World!\") # Do your magic here...\n return app\n```\n\nIf you want the ability to run your Dash application locally, you can add the following code to the bottom of your `app.py` file.\n\n```python\n# Make sure to set the DEBUG and PORT environment variables.\nif __name__ == \"__main__\" and os.getenv('DEBUG') == 'True':\n create_app().run_server(debug=True, port=os.getenv('PORT', 8050))\n```\n\n### Configuring OpenDash\nCreate an `open-dash.config.json` file in the root of your project. The configuration file should contain the following fields:\n\n```json\n{\n \"warmer\": true, // Optional - Whether to include a warmer function in the output bundle.\n \"export-static\": true, // Optional - Whether to include an index.html and other static files in the output bundle.\n \"data-path\": \"path/to/data\", // Optional - The path to the data directory.\n \"venv-path\": \"path/to/venv\", // Optional - The path to the virtual environment. If not provided, the system Python interpreter is used.\n \"excluded-directories\": [\"__pycache__\", \".git\"], // Optional - Directories to exclude from the output bundle.\n \"domain-name\": \"example.com\", // Optional - The domain name of the deployed application.\n \"target-base-path\": \"path/to/target\", // Optional - The path to the target directory. If not provided, the source path's parent folder is used.\n \"source-path\": \"path/to/source\", // Optional - The path to the source directory. If not provided, the current working directory is used.\n \"fingerprint\": {\n \"version\": true, // Whether to include the system package version in the fingerprint.\n \"method\": \"last-modified\" // The method to use for fingerprinting. Options: \"none\", \"global\", \"last-modified\"\n }\n}\n```\n\nIf you do not provide a configuration file, OpenDash will use the default configuration:\n\n```json\n{\n \"warmer\": true,\n \"source-path\": \".\",\n \"export-static\": true,\n \"target-base-path\": \"..\",\n \"excluded-directories\": [],\n \"fingerprint\": {\n \"version\": true,\n \"method\": \"last-modified\"\n }\n}\n```\n\n\n### Generating Artifacts\nRun the following commands to generate the artifacts.\n\n```bash\npython -m pip install open-dash\n\n# NOTE: Run the next command in virtual environment because open-dash installs your application's dependencies.\n# --config-path -> Path to the configuration file. If not provided, the fallback will be an open-dash.config.json file in the current directory, or a default configuration if neither is found.\nopen-dash bundle --config-path path/to/open-dash.config.json\n\n# The output .open-dash folder will be a sibling of the source folder.\n```\n\n## File Fingerprinting\nDash fingerprints JS and CSS files to help with cache invalidation. The fingerprint is generated based on each file's \nlast modified time. This fingerprint approach works if assets are fetched from the same server. However, if you deploy\nyour assets to S3 and your server to Lambda, the fingerprint will be different for each. To give devs flexibility, \nOpenDash supports multiple fingerprinting approaches:\n1. **Last Modified Time** - The last modified time is used to generate the fingerprint if the index.html file is \ngenerated at the same time as the static assets. This is the default fingerprinting method used by Dash.\n2. **Global Fingerprint** - The fingerprint is generated based on the build time of the assets. This is ideal if you\nare going to serve assets from S3, the index page from Lambda, and override the fingerprints returned by the index.html.\n\n## Suggested Architecture (Not Included in OpenDash)\n\n\n1. **CloudFront** - Serves static assets from the S3 bucket and falls back to the Dash server lambda for other requests. Remember to set the default root object to `index.html`.\n2. **S3 Bucket** - Stores the static assets. Make sure to block public access and give CloudFront read access to the bucket. See this [AWS Guide](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/private-content-restricting-access-to-s3.html) for more information.\n\nOptional infrastructure, depending on your application:\n\n3. **Lambda@Edge Origin Request Function** - A Lambda function triggered by CloudFront to sign the Dash server lambda requests and configure headers.\n4. **Dash Server Lambda** - A Lambda function that runs the Dash server. This function is triggered by CloudFront when the requested path does not match a static asset. Make sure you define the `DOMAIN_NAME` environment variable. \n\n > NOTE: It is possible for the server lambda to not get called if your application is a SPA without a backend. Monitor your function's logs and adjust your architecture accordingly.\n\n5. **Warmer Function** - A Lambda function that pings the Dash server lambda to keep it warm. This function is triggered by the EventBridge CRON.\n6. **EventBridge CRON** - A CloudWatch event that triggers the warmer function every 5 minutes.\n\n## Zero-Config Deployments\nYou can deploy your Dash application to AWS using the [Zonk\u00e9 dashboard](https://zonke.dev). The dashboard offers the following features:\n1. **Zero-Config** - Deploy your Dash application to AWS without any configuration.\n2. **Continuous Deployment** - Automatically deploy your Dash application when you push to your Git repository.\n3. **Other Deployment Options** - Deploy your Dash application to other configurations, such as ECS Fargate/EC2.\n\n## Acknowledgments\nOpenDash was heavily inspired by, but not affiliated with, [OpenNext](https://github.com/opennextjs/opennextjs-aws).\n\n---\n\nMaintained by the [Zonk\u00e9 team](https://zonke.dev) | [Discord](https://discord.gg/CRNPV8BkjC) | [Twitter](https://x.com/ZonkeInc) | [LinkedIn](https://www.linkedin.com/company/zonke-inc)\n",
"bugtrack_url": null,
"license": null,
"summary": "Open Dash packages Plotly dash applications for deployment to AWS S3 and Lambda. Developed by Zonk\u00e9.",
"version": "0.1.0",
"project_urls": {
"Documentation": "https://github.com/zonke-inc/open-dash#readme",
"Homepage": "https://zonke.dev",
"Issues": "https://github.com/zonke-inc/open-dash/issues",
"Source": "https://github.com/zonke-inc/open-dash"
},
"split_keywords": [
"dash",
" deployment",
" serverless",
" zonke"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f1ecbeab8dfc8428a5e0dba6a5ffe1927fca0249f46f9be06354492f6b171e55",
"md5": "93733fcbb3ad778da4309a27399b9310",
"sha256": "cebbbf676774bbe89c84292975bdf28625b2c423956f094e34383176dc9ea4d8"
},
"downloads": -1,
"filename": "open_dash-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "93733fcbb3ad778da4309a27399b9310",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 18625,
"upload_time": "2025-01-08T21:28:08",
"upload_time_iso_8601": "2025-01-08T21:28:08.624889Z",
"url": "https://files.pythonhosted.org/packages/f1/ec/beab8dfc8428a5e0dba6a5ffe1927fca0249f46f9be06354492f6b171e55/open_dash-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "29e018a168b252f4c5cccf119a1385ebe9458f5f70b0ae1d7544dce8e7807fc1",
"md5": "2d68bc35705a44fe786839592dc2d239",
"sha256": "3b93664536f976830188edba880c8e3f57da56ebebc1f11c8f9296864b8fe7b9"
},
"downloads": -1,
"filename": "open_dash-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "2d68bc35705a44fe786839592dc2d239",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 15915,
"upload_time": "2025-01-08T21:28:11",
"upload_time_iso_8601": "2025-01-08T21:28:11.746352Z",
"url": "https://files.pythonhosted.org/packages/29/e0/18a168b252f4c5cccf119a1385ebe9458f5f70b0ae1d7544dce8e7807fc1/open_dash-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-08 21:28:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "zonke-inc",
"github_project": "open-dash#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "open-dash"
}
