Static website on DigitalOcean App Platform

The module automates the deployment of a static website on the DigitalOcean App Platform, supports custom domain configuration, custom 404 status code responses, and fallback behavior for requests to missing documents.

Features

Fetching the source code from repositories, including public Git-based repositories or private repositories hosted on GitHub or GitLab, for deployment
Fetching the container image from DigitalOcean Container Registry (DOCR) or Docker Hub container image library for deployment
Configuring parameters for automatically scaling the component based on CPU utilization
Providing flexibility in specifying build commands and deployment options
Configuring custom domains and subdomains for the static website
Implementing routing for a custom page to handle errors
Setting the default URL in the DigitalOcean domain zone ondigitalocean.app

Requirements

Deploying from the Git-based repositories

To deploy the static site from the Git-based repositories using this module, ensure the DigitalOcean App Platform grants access to the Git repository with the source code and uses the arguments accordingly:

For any publicly accessible repositories:
* Set source_type to git
GitHub or GitLab private repositories integration:
* If the source code resides in a GitHub or GitLab private repository, ensure the following prerequisites are met:
- for GitHub: the variable source_type is github and The Access to GitHub Repositories for DigitalOcean App Platform is Granted
- for GitLab: the variable source_type is gitlab and The Access to GitLab Repositories for DigitalOcean App Platform is Granted

Deploying from the container images

To deploy the static site from the container image stored on a private DockerHub container registry, ensure access to the container registry by providing a registry_credentials variable with the credentials in the format username:token

For the images stored on DOCR, providing additional credentials is not needed.

NOTE: the module verifies the creation of custom DNS records using the dig utility, for this it runs the local command aimed for usage in Linux systems only. The default TTL for DNS records is 30 minutes. Recreating the site within a period shorter than the TTL may cause prolonged checks, resulting in longer terraform apply execution times.

Once you have a Corewide Solutions Portal account, this one-time action will use your browser session to retrieve credentials:

 shellterraform login solutions.corewide.com

Provision instructions

Initialize mandatory providers:

digitalocean/digitalocean

Copy and paste into your Terraform configuration and insert the variables:

 hclmodule "tf_do_app_platform_static_website" {
  source  = "solutions.corewide.com/digitalocean/tf-do-app-platform-static-website/digitalocean"
  version = "~> 1.0.0"

  # specify module inputs here or try one of the examples below
  ...
}

Initialize the setup:

 shellterraform init

Define update strategy

Corewide DevOps team strictly follows Semantic Versioning Specification to provide our clients with products that have predictable upgrades between versions. We recommend pinning patch versions of our modules using pessimistic constraint operator (~>) to prevent breaking changes during upgrades.

To get new features during the upgrades (without breaking compatibility), use ~> 1.0 and run terraform init -upgrade

For the safest setup, use strict pinning with version = "1.0.0"

$350

BUY

License

v1.0.0 released 4 weeks ago

Changelog

Features

Fetching the source code from repositories, including public Git-based repositories or private repositories hosted on GitHub or GitLab, for deployment
Fetching the container image from DigitalOcean Container Registry (DOCR) or Docker Hub container image library for deployment
Configuring parameters for automatically scaling the component based on CPU utilization
Providing flexibility in specifying build commands and deployment options
Configuring custom domains and subdomains for the static website
Implementing routing for a custom page to handle errors
Setting the default URL in the DigitalOcean domain zone ondigitalocean.app

Requirements

Deploying from the Git-based repositories

For any publicly accessible repositories:
* Set source_type to git
GitHub or GitLab private repositories integration:
* If the source code resides in a GitHub or GitLab private repository, ensure the following prerequisites are met:
- for GitHub: the variable source_type is github and The Access to GitHub Repositories for DigitalOcean App Platform is Granted
- for GitLab: the variable source_type is gitlab and The Access to GitLab Repositories for DigitalOcean App Platform is Granted

Deploying from the container images

For the images stored on DOCR, providing additional credentials is not needed.

NOTE: the module verifies the creation of custom DNS records using the dig utility, for this it runs the local command aimed for usage in Linux systems only. The default TTL for DNS records is 30 minutes. Recreating the site within a period shorter than the TTL may cause prolonged checks, resulting in longer terraform apply execution times.

Minimal setup deploys a static site from a public Git repository to the default DigitalOcean App domain zone using only the mandatory parameters. Without specifying, the DNS zone domain name will be in the default DigitalOcean domain zone ondigitalocean.app:

 hclmodule "static_website" {
  source  = "solutions.corewide.com/digitalocean/tf-do-app-platform-static-website/digitalocean"
  version = "~> 1.0"

  project_name = "project-name"
  source_type  = "git"
  source_name  = "https://github.com/owner-name/repo-name.git"
}

Custom setup deploys a static site from a private Git repository to a custom DigitalOcean DNS zone using custom build commands, environment variables, and other configurable parameters for build and runtime:

 hclresource "digitalocean_domain" "managed" {
  name = "example.com"
}

module "static_website" {
  source  = "solutions.corewide.com/digitalocean/tf-do-app-platform-static-website/digitalocean"
  version = "~> 1.0"

  project_name     = "project-name"
  source_type      = "github"
  source_name      = "owner-name/repo-name"
  source_version   = "main"
  build_command    = "npm run build"
  output_directory = "public"
  zone_name        = digitalocean_domain.managed.name
  error_document   = "index.html"

  dns_records = [
    "site.${digitalocean_domain.managed.id}",
    "site-test.${digitalocean_domain.managed.id}",
  ]

  environment_variables = {
    SECRET_TOKEN = {
      value = "QgLfwlsdfmmsdavqT8TFiYUfV3UCGApOniwnl"
      type  = "SECRET"
    }

    BACKEND_DOMAIN = {
      value = "foo.bar"
    }
  }
}

Advanced setup deploys a static site from a container image in the DigitalOcean Container Registry (DOCR) to a custom DigitalOcean DNS zone, with DNS managed by the DigitalOcean DNS module:

 hclmodule "dns" {
  source  = "solutions.corewide.com/digitalocean/tf-do-dns/digitalocean"
  version = "~> 1.1"

  zone_name   = "example.com"
  create_zone = true
}

module "static_website" {
  source  = "solutions.corewide.com/digitalocean/tf-do-app-platform-static-website/digitalocean"
  version = "~> 1.0"

  project_name   = "project-name"
  source_type    = "DOCR"
  source_name    = "project-container-registry"
  source_version = "project-image"
  image_tag      = "production"
  build_command  = "npm run build"

  autoscaling = {
    min_instance_count = 1
    max_instance_count = 2
    cpu_percent        = 70
  }

  dns_records = [
    "site.${module.dns.zone}",
    "site-test.${module.dns.zone}",
  ]

  environment_variables = {
    SECRET_TOKEN = {
      value = "QgLfwlsdfmmsdavqT8TFiYUfV3UCGApOniwnl"
      type  = "SECRET"
    }

    BACKEND_DOMAIN = {
      value = "foo.bar"
    }
  }
}

module "dns_records" {
  source  = "solutions.corewide.com/digitalocean/tf-do-dns/digitalocean"
  version = "~> 1.1"

  zone_name = module.dns.zone

  records = {
    "site" = {
      type  = "CNAME"
      value = [replace(module.static_website.default_ingress, "https://", "")]
    }

    "site-test" = {
      type  = "CNAME"
      value = [replace(module.static_website.default_ingress, "https://", "")]
    }
  }
}

Advanced setup deploys a static site from a private Git repository to a custom Cloudflare DNS zone, with DNS managed by the Cloudflare DNS module:

 hclmodule "dns" {
  source  = "solutions.corewide.com/cloudflare/tf-cloudflare-dns/cloudflare"
  version = "~> 1.0"

  account_id  = "1234567890a1234567890b1234567890"
  zone_name   = "example.com"
  create_zone = true
}

module "static_website" {
  source  = "solutions.corewide.com/digitalocean/tf-do-app-platform-static-website/digitalocean"
  version = "~> 1.0"

  project_name     = "project-name"
  source_type      = "github"
  source_name      = "owner-name/repo-name"
  source_version   = "main"
  build_command    = "npm run build"
  output_directory = "public"
  error_document   = "index.html"

  dns_records = [
    "site.${module.dns.zone.id}",
    "site-test.${module.dns.zone.id}",
  ]

  environment_variables = {
    SECRET_TOKEN = {
      value = "QgLfwlsdfmmsdavqT8TFiYUfV3UCGApOniwnl"
      type  = "SECRET"
    }

    BACKEND_DOMAIN = {
      value = "foo.bar"
    }
  }
}

module "dns_records" {
  source  = "solutions.corewide.com/cloudflare/tf-cloudflare-dns/cloudflare"
  version = "~> 1.0"

  account_id = "1234567890a1234567890b1234567890"
  zone_name  = module.dns.zone.id

  records = {
    "site" = {
      type  = "CNAME"
      value = [replace(module.static_website.default_ingress, "https://", "")]
    }

    "site-test" = {
      type  = "CNAME"
      value = [replace(module.static_website.default_ingress, "https://", "")]
    }
  }
}

Minimal setup deploys a static site from a container image stored in the DigitalOcean Container Registry (DOCR) to the default DigitalOcean App domain zone using only the mandatory parameters. Without specifying, the DNS zone domain name will be in the default DigitalOcean domain zone ondigitalocean.app:

 hclmodule "static_website" {
  source  = "solutions.corewide.com/digitalocean/tf-do-app-platform-static-website/digitalocean"
  version = "~> 1.0"

  project_name   = "project-name"
  source_type    = "DOCR"
  source_name    = "project-container-registry"
  source_version = "project-image"
}

Variable	Description	Type	Default	Required	Sensitive
`build_command`	Command to build the static site. If not set, DigitalOcean tries to use appropriate build commands based on the detected technology stack	`string`		yes	no
`catchall_document`	The name of the document to use as the fallback for any requests to documents that are not found when serving this static site	`string`		yes	no
`error_document`	The name of the error document to use when serving the static site	`string`		yes	no
`image_tag`	The tag of the image to use for deploy. Defaults to `latest` if not provided	`string`		yes	no
`index_document`	The name of the index document to use when serving the static site. If it is `null` DigitalOcean defaults to serving a file named `index.html` located in the root of the output directory	`string`		yes	no
`output_directory`	Directory in the repo containing the built assets, relative to the build context. If not set, App Platform will automatically scan for these directory names: `_static`, `dist`, `public`	`string`		yes	no
`project_name`	The name of the DigitalOcean App Platform application and its component `static site`	`string`		yes	no
`registry_credentials`	The credentials required to access a private Docker Hub or GitHub registry, in the following syntax `username:token`	`string`		yes	no
`source_directory`	An optional path to the working directory to use for the build. Specify the directory that contains the static site source code if this code is stored in the monorepo	`string`		yes	no
`source_name`	The Git repository URL, repository name and repository owner, or container registry name containing the static site source code or image	`string`		yes	no
`source_type`	The types of SCM system or container registry (available values: `git`, `github`, `gitlab`, `DOCR`, or `DOCKER_HUB`)	`string`		yes	no
`autoscaling`	Configuration for automatically scaling static site deployed from the container image based on metrics	`object`		no	no
`autoscaling.cpu_percent`	Settings for scaling the static site based on CPU utilization. The average target CPU utilization for the instance	`number`	`70`	no	no
`autoscaling.max_instance_count`	The maximum amount of instances for this static site. Must be more than `min_instance_count`	`number`	`2`	no	no
`autoscaling.min_instance_count`	The minimum amount of instances for this static site. Must be less than `max_instance_count`	`number`	`1`	no	no
`cors_config`	Configuration for CORS settings	`object`	`{}`	no	no
`cors_config.allow_credentials`	Indicates whether the browser should include credentials in cross-origin requests	`bool`		no	no
`cors_config.allow_headers`	Set of request headers that are allowed during the actual request or preflight request	`list(string)`	`[]`	no	no
`cors_config.allow_methods`	Set of HTTP methods that are allowed for cross-origin requests	`list(string)`	`[]`	no	no
`cors_config.allow_origins`	Set of origins that are allowed to access the site	`object`		no	no
`cors_config.allow_origins.exact`	The origin will be allowed only if the client's origin exactly matches the provided value	`list(string)`	`[]`	no	no
`cors_config.allow_origins.prefix`	The origin will be allowed only if the client's origin matches the provided regex	`list(string)`	`[]`	no	no
`cors_config.allow_origins.regex`	The origin will be allowed only if the beginning of the client's origin matches the provided value	`list(string)`	`[]`	no	no
`cors_config.expose_headers`	Set of response headers that are exposed to the client application	`list(string)`	`[]`	no	no
`cors_config.max_age`	Time in seconds that the browser should cache the preflight response	`string`		no	no
`dns_records`	The list of custom domains. Put the primary domain first on this list always	`list(string)`	`[]`	no	no
`environment_variables`	Environment variables for the static site build process and runtime usage	`map(map(string))`	`{}`	no	no
`health_check`	Configuration service health check settings	`object`	`{}`	no	no
`health_check.failure_threshold`	The number of failed health checks before being considered unhealthy	`number`	`3`	no	no
`health_check.http_path`	The route path used for the HTTP health check ping	`string`	`/`	no	no
`health_check.initial_delay_seconds`	The number of seconds to wait before beginning health checks	`number`	`5`	no	no
`health_check.period_seconds`	The number of seconds to wait between health checks	`number`	`10`	no	no
`health_check.port`	The port on which health check will be performed	`number`	`80`	no	no
`health_check.timeout_seconds`	The number of seconds after which the check times out	`number`	`5`	no	no
`http_port`	The internal port on which the service process listens for incoming HTTP requests	`number`	`80`	no	no
`source_version`	The name of the branch, or image name to use for deploy	`string`	`main`	no	no
`zone_name`	The name of DigitalOcean DNS zone. Must be set to grant DigitalOcean automatic management of App Platform DNS records	`string`		no	no

Output	Description	Type	Sensitive
`application_parameters`	Contains all the parameters of the deployed application	`resource`	no
`default_ingress`	Automatically generated default ingress URL to access the static website	`attribute`	no
`dns_records`	Contains all the domain's attributes	`computed`	no
`dns_zone`	The name of the created/existing DNS zone or a message indicating it's not set	`computed`	no