chore: add deployment docs

README.md

@@ -11,7 +11,7 @@ Improved Go Playground powered by Monaco Editor and React - [https://goplay.tool
 
 🎉 **Check new upcoming features in latest beta at [beta.goplay.tools](https://beta.goplay.tools)**
 
-![alt text](docs/demo.gif)
+![alt text](docs/img/demo.gif)
 
 ## Features
 
@@ -26,24 +26,9 @@ Improved Go Playground powered by Monaco Editor and React - [https://goplay.tool
 
 And more !
 
-## Installation
+## Installation & deployment
 
-### Docker Container (recommended)
-
-Playground is available as Docker image in [Docker Hub](https://hub.docker.com/r/x1unix/go-playground) and [GitHub Container Registry](https://github.com/x1unix/go-playground/pkgs/container/go-playground%2Fgo-playground).
-
-See [wiki](https://github.com/x1unix/go-playground/wiki/Docker) for usage info.
-
-### Building from source
-
-Service can be built from source (**Go 1.21+** and **Node.js** required):
-
-```bash
-git clone https://github.com/x1unix/go-playground.git
-cd go-playground
-make
-sudo make install
-```
+Please check [deployment documentation](./docs/deployment/README.md).
 
 ### Third-party credits
 
@@ -59,8 +44,8 @@ Please refer to [CONTRIBUTING.md](CONTRIBUTING.md) and [HACKING.md](HACKING.md)
 
 <a href="https://gno.land/?from=goplay-tools" target="_blank">
     <picture>
-        <source media="(prefers-color-scheme: dark)" srcset="./docs/sponsors/gnoland-dark.svg" width="480">
-        <img alt="Gno.land logo" width="480" src="./docs/sponsors/gnoland-light.svg">
+        <source media="(prefers-color-scheme: dark)" srcset="./docs/img/sponsors/gnoland-dark.svg" width="480">
+        <img alt="Gno.land logo" width="480" src="./docs/img/sponsors/gnoland-light.svg">
     </picture>
 </a>
 

docs/deployment/README.md

@@ -0,0 +1,12 @@
+# Deployment
+
+Here are examples of various application deployment options.
+
+## Cloud
+
+* [Google Cloud Run](./gcloud)
+
+## Bare-metal
+
+* [Docker](./docker) - Docker container deployment using `docker-compose`
+* [systemd](./systemd) - Container-less deployment as systemd unit.

docs/deployment/docker/README.md

@@ -0,0 +1,54 @@
+# Deployment using docker-compose
+
+## Using prebuilt image
+
+Prebuilt Docker image is available on [Docker Hub](https://hub.docker.com/r/x1unix/go-playground) and [GitHub Container Registry](https://github.com/x1unix/go-playground/pkgs/container/go-playground%2Fgo-playground)
+
+### Starting container
+
+Download the [compose.yaml](./compose.yaml) file and run `docker-compose` to bootstrap the service:
+
+```shell
+# Create container and start the service.
+docker-compose up -d
+
+# Ensure that service is running.
+docker-compose ps
+```
+
+### Environment variables
+
+Playground server can be configured using environment variables described below.
+
+| Environment Variable   | Example                        | Description                                                    |
+| ---------------------- | ------------------------------ | -------------------------------------------------------------- |
+| `GOROOT`               | `/usr/local/go`                | Go root location. Uses `go env GOROOT` as fallback.            |
+| `APP_DEBUG`            | `false`                        | Enables debug logging.                                         |
+| `APP_PLAYGROUND_URL`   | `https://play.golang.org`      | Official Go playground service URL.                            |
+| `APP_GOTIP_URL`        | `https://gotipplay.golang.org` | GoTip playground service URL.                                  |
+| `APP_BUILD_DIR`        | `/var/cache/wasm`              | Path to store cached WebAssembly builds.                       |
+| `APP_CLEAN_INTERVAL`   | `10m`                          | WebAssembly build files cache cleanup interval.                |
+| `APP_SKIP_MOD_CLEANUP` | `1`                            | Disables WASM builds cache cleanup.                            |
+| `APP_PERMIT_ENV_VARS`  | `GOSUMDB,GOPROXY`              | Restricts list of environment variables passed to Go compiler. |
+
+## Building custom image
+
+Use **make** to build Docker image from sources:
+
+```shell
+make docker [...params]
+```
+
+### Required params
+
+| Parameter     | Description                |
+| ------------- | -------------------------- |
+| `TAG`         | Image tag (version)        |
+| `DOCKER_USER` | Docker repository user     |
+| `DOCKER_PASS` | Docker repository password |
+
+### Optional params
+
+| Parameter     | Defaults               | Description                |
+| ------------- | ---------------------- | -------------------------- |
+| `IMG_NAME`    | `x1unix/go-playground` | Image tag (version)        |

docs/deployment/docker/compose.yml

@@ -0,0 +1,14 @@
+version: '2'
+services:
+  playground:
+    # 'latest' used only for example purposes.
+    # It's strongly recommended to use a specific version (tag).
+    #
+    # Also, you can use image from GitHub Container Registry
+    #image: ghcr.io/x1unix/go-playground/go-playground:latest
+    image: x1unix/go-playground:latest
+    restart: unless-stopped
+    ports:
+      - 8000:8000
+    environment:
+      APP_CLEAN_INTERVAL: '30m'

docs/deployment/gcloud/.gitignore

@@ -0,0 +1,13 @@
+# Temporary files
+.terraform
+*.backup
+*.tfstate
+
+# HCL vars except example
+*.tfvars
+!example.tfvars
+
+# Temporary plan options
+tplan
+tfplan
+*.tplan

docs/deployment/gcloud/README.md

@@ -0,0 +1,7 @@
+# Google Cloud Run Deployment
+
+## Prerequisites
+
+* [OpenTofu](https://opentofu.org) or Terraform.
+* [gcloud](https://cloud.google.com/sdk/docs/install) tool.
+* [Google Cloud](https://cloud.google.com/) project.

docs/deployment/gcloud/example.tfvars

@@ -0,0 +1,9 @@
+app_env = "prod"
+app_version = "latest"           # Deployed app version, replace "latest" with Docker image tag.
+project_id = "your gcp project ID"
+region = "us-central1"          # Desired region for deployment
+env_vars = {
+  # Put here custom environment variables, optional.
+  # "FOO" = "bar"
+}
+

docs/deployment/gcloud/main.tf

@@ -0,0 +1,122 @@
+# See: https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/cloud_run_v2_service
+
+# Beta provider is required for "empty_dir" storage type.
+provider "google-beta" {
+  project = var.project_id
+  region  = var.region
+}
+
+resource "google_cloud_run_v2_service" "default" {
+  provider = google-beta
+  name     = "gpg-${var.app_env}"
+  location = var.region
+  launch_stage = "BETA"
+
+  template {
+    scaling {
+      min_instance_count = 1
+      max_instance_count = 5
+    }
+
+    volumes {
+      name = "gpg-build-cache-${var.app_env}"
+      empty_dir {
+        medium = "MEMORY"
+        size_limit = "256Mi"
+      }
+    }
+
+    containers {
+      image = "x1unix/go-playground:${var.app_version}"
+      ports {
+        name = "http1"
+        container_port = 8000
+      }
+
+      resources {
+        cpu_idle = true
+        startup_cpu_boost = false
+        limits = {
+          cpu = "1"
+          memory = "512Mi"
+        }
+      }
+
+      env {
+        name = "APP_LOG_FORMAT"
+        value = "console"
+      }
+
+      # Disable cache cleanup for stateless containers.
+      env {
+        name = "APP_SKIP_MOD_CLEANUP"
+        value = "1"
+      }
+
+      env {
+        name = "SENTRY_ENVIRONMENT"
+        value = var.app_env
+      }
+
+      env {
+        name = "SENTRY_RELEASE"
+        value = "v${var.app_version}"
+      }
+
+      env {
+        name = "SENTRY_DSN"
+        value = var.sentry_dsn
+      }
+
+      dynamic "env" {
+        for_each = var.env_vars
+        content {
+          name = env.key
+          value = env.value
+        }
+      }
+
+      # Use WASM build cache directory.
+      env {
+        name = "APP_BUILD_DIR"
+        value = "/var/cache/wasm-builds"
+      }
+
+      volume_mounts {
+        name = "gpg-build-cache-${var.app_env}"
+        mount_path = "/var/cache/wasm-builds"
+      }
+
+      startup_probe {
+        http_get {
+          path = "/api/version"
+          port = 8000
+        }
+        initial_delay_seconds = 10
+        period_seconds = 10
+        timeout_seconds = 5
+        failure_threshold = 3
+      }
+    }
+  }
+
+  traffic {
+    percent = 100
+    type = "TRAFFIC_TARGET_ALLOCATION_TYPE_LATEST"
+  }
+}
+
+# Make service public.
+# See: https://cloud.google.com/run/docs/authenticating/public
+resource "google_cloud_run_service_iam_binding" "run_invoker" {
+  location = google_cloud_run_v2_service.default.location
+  service  = google_cloud_run_v2_service.default.name
+  role     = "roles/run.invoker"
+  members = [
+    "allUsers"
+  ]
+}
+
+output "url" {
+  value = google_cloud_run_v2_service.default.uri
+}

docs/deployment/gcloud/variables.tf

@@ -0,0 +1,31 @@
+variable "project_id" {
+  description = "GCP Project ID"
+  type = string
+}
+
+variable "region" {
+  description = "The region of the GCP project"
+  type = string
+}
+
+variable "app_env" {
+  description = "Deployment environment"
+  type = string
+}
+
+variable "app_version" {
+  description = "Better Go Playground application version"
+  type = string
+}
+
+variable "sentry_dsn" {
+  description = "Sentry DSN"
+  type = string
+  default = ""
+}
+
+variable "env_vars" {
+  description = "key-value pair of custom environment variables."
+  type = map(string)
+  default = {}
+}

docs/deployment/systemd/README.md

@@ -0,0 +1,36 @@
+# Deployment as systemd unit
+
+> [!TIP]
+> See [HACKING.md](../../../HACKING.md) for development documentation.
+
+## Prerequisites
+
+* GNU or BSD Make
+* Git
+* Go 1.22+
+* [Node Version Manager](https://github.com/nvm-sh/nvm) or Node.js 20 (`lts/iron`)
+* [Yarn](https://yarnpkg.com/) package manager.
+
+## Building
+
+Close and build this repository:
+
+```shell
+git clone https://github.com/x1unix/go-playground.git
+cd go-playground
+make
+```
+
+## Installation
+
+After building the app, install application and systemd unit:
+
+```shell
+sudo make install
+```
+
+Check if service is running:
+
+```shell
+systemctl status better-go-playground.service
+```

docs/deployment/systemd/better-go-playground.service

@@ -0,0 +1 @@
+../../../build/better-go-playground.service