Merge remote-tracking branch 'refs/remotes/origin/main'

Author: gregsadetsky

docs/deployment-guides/_category_.json

@@ -2,5 +2,5 @@
   "label": "Deployment Guides",
   "position": 3,
   "collapsible": false,
-  "collapsed": false,
+  "collapsed": false
 }

docs/exhaustive-documentation/_category_.json

@@ -0,0 +1,6 @@
+{
+  "label": "Exhaustive Documentation",
+  "position": 4,
+  "collapsible": false,
+  "collapsed": false
+}

docs/exhaustive-documentation/crons.md

@@ -0,0 +1,53 @@
+---
+sidebar_position: 2
+---
+
+# Crons
+
+You can specify crons in your `disco.json` file:
+```json
+{
+    "version": "1.0",
+    "services": {
+        "web": {
+            "port": 8080,
+            "command": "./bin/serve.sh"
+        },
+        "mycron": {
+            "type": "cron",
+            "schedule": "0 * * * *",
+            "command": "./bin/crons/hour.sh"
+        }
+    }
+}
+```
+
+## Useful Examples
+
+Here are a few useful examples of `crontab` notation to get you started:
+```json
+{
+    "version": "1.0",
+    "services": {
+        "web": {
+            "port": 8080,
+            "command": "./bin/serve.sh"
+        },
+        "minutecron": {
+            "type": "cron",
+            "schedule": "* * * * *",
+            "command": "./bin/cron/oneminute.sh"
+        },
+        "hourcron": {
+            "type": "cron",
+            "schedule": "0 * * * *",
+            "command": "./bin/cron/onehour.sh"
+        },
+        "daycron": {
+            "type": "cron",
+            "schedule": "0 0 * * *",
+            "command": "./bin/cron/oneday.sh"
+        }
+    }
+}
+```

docs/exhaustive-documentation/environment-variables.md

@@ -0,0 +1,100 @@
+---
+sidebar_position: 1
+---
+
+# Environment Variables
+
+To set environment variables for you project, you can use the CLI commands:
+
+```bash
+disco env:set --project my-project VAR_NAME=value
+```
+
+You can set many of them at once:
+```bash
+disco env:set --project my-project VAR_NAME=value OTHER_VAR="other value"
+```
+
+To retrieve a specific value:
+```bash
+disco env:get --project my-project VAR_NAME
+```
+
+Or to retrieve all key/values:
+```bash
+disco env:list --project my-project
+```
+
+## Using Environment Variables in your App
+
+Your code can use environment variables like anywhere else.
+
+E.g. in Bash
+```bash
+echo "Hello $VAR_NAME"
+```
+in Python
+```python
+import os
+print(f"Hello {os.getenv('VAR_NAME')")
+```
+or in JavaScript with NodeJS
+```javascript
+console.log(`Hello ${process.env.VAR_NAME}`)
+```
+
+## Using Environment Variables When Building Images
+
+When building Docker images, we need to be careful to avoid including the variables in the images. Disco uses the recommended way to expose environment variables without baking them into the images.
+
+See Docker documentation about [Build Secrets](https://docs.docker.com/build/building/secrets/) for more info.
+
+### Dot Env (.env)
+
+You can either access all of the variables as a `.env` file, where each line is `VAR_NAME=value`
+
+```Dockerfile
+RUN --mount=type=secret,id=.env your-command
+```
+
+Docker will make the file available as `/run/secrets/.env` for that one command. If the base image you're using supports it, you could use the `.env` file as follows
+```Dockerfile
+RUN --mount=type=secret,id=.env env $(cat /run/secrets/.env | xargs) your-command
+```
+
+That way, `your-command` will have the environment loaded just before it runs.
+
+Make sure to not set the environment variable with `export`, because it would set it in the environment of the image and it would mean your secrets have leaked.
+
+### Individual Variable
+
+If you only want access to a single variable, you can do this
+
+```Dockerfile
+RUN --mount=type=secret,id=VAR_NAME your-command
+```
+
+and `/run/secrets/VAR_NAME` will contain the value of the variable.
+
+You could add many variables using this method:
+```Dockerfile
+RUN --mount=type=secret,id=VAR_NAME --mount=type=secret,id=OTHER_VAR your-command
+```
+
+### Specifying the File Path and File Name to Use
+
+If you need to use a specific path for the files that Docker makes available, instead of e.g. `/run/secrets/.env`, you can specify it with `target`.
+
+The [Docker documentation](https://docs.docker.com/build/building/secrets/#target) contains this example
+```Dockerfile
+RUN --mount=type=secret,id=aws,target=/root/.aws/credentials \
+    aws s3 cp ...
+```
+We can adapt it to Disco's environment variables like
+```bash
+disco env:set --projecct my-project AWS_CREDENTIALS='...'
+```
+```Dockerfile
+RUN --mount=type=secret,id=AWS_CREDENTIALS,target=/root/.aws/credentials \
+    aws s3 cp ...
+```

docs/exhaustive-documentation/images.md

@@ -0,0 +1,202 @@
+---
+sidebar_position: 6
+---
+
+# Images
+
+Each service uses a Docker image.
+
+## Specifying a Dockerfile
+
+You can define many images in `disco.json` and refer to them in your services.
+
+```json
+{
+    "version": "1.0",
+    "services": {
+        "web": {
+            "port": 8080,
+            "command": "./bin/serve.sh",
+            "image": "webimage"
+        }
+    },
+    "images": {
+        "webimage": {
+            "dockerfile": "Dockerfile",
+            "context": "."
+        }
+    }
+}
+```
+
+## Default Image
+
+You can avoid talking about images in your `disco.json` file by relying on the default of using the `Dockerfile` and build context at the root of the repository.
+
+```json
+{
+    "version": "1.0",
+    "services": {
+        "web": {
+            "port": 8080,
+            "command": "./bin/serve.sh"
+        }
+    }
+}
+```
+
+This `disco.json` above uses the defaults. More on this below.
+
+When you don't specify the image to use for a service, Disco will default to the image named `default`.
+
+Those two `disco.json` are equivalent, defining `"image"` or not in the definition of `"web"`:
+
+```json
+{
+    "version": "1.0",
+    "services": {
+        "web": {
+            "port": 8080,
+            "command": "./bin/serve.sh"
+        }
+    },
+    "images": {
+        "default": {
+            "dockerfile": "Dockerfile",
+            "context": "."
+        }
+    }
+}
+```
+and
+```json
+{
+    "version": "1.0",
+    "services": {
+        "web": {
+            "port": 8080,
+            "command": "./bin/serve.sh",
+            "image": "default"
+        }
+    },
+    "images": {
+        "default": {
+            "dockerfile": "Dockerfile",
+            "context": "."
+        }
+    }
+}
+```
+
+Also, when not defining the `default` image, Disco will assume the default value shown above. That is, the `Dockerfile` at the root of the repository, the build context as well. Meaning that this third `disco.json` is also equivalent:
+```json
+{
+    "version": "1.0",
+    "services": {
+        "web": {
+            "port": 8080,
+            "command": "./bin/serve.sh"
+        }
+    }
+}
+```
+
+In other words, if the `Dockerfile` you want to use is at the root of the repository, and the build context is also the root of the repository, you can just avoid thinking about images in your `disco.json`.
+
+## Many images, many services
+
+Each service can use a different Docker image.
+
+```json
+{
+    "version": "1.0",
+    "services": {
+        "web": {
+            "port": 8080,
+            "command": "./bin/serve.sh",
+            "image": "webimage"
+        },
+        "worker": {
+            "command": "./bin/worker.sh",
+            "image": "workerimage"
+        }
+    },
+    "images": {
+        "webimage": {
+            "dockerfile": "Dockerfile",
+            "context": "."
+        },
+        "workerimage": {
+            "dockerfile": "Dockerfile.worker",
+            "context": "."
+        }
+    }
+}
+```
+
+## Using Dockerfiles in Sub-Directories
+
+You can pass the path to your Dockerfile, and also the path for the [local context](https://docs.docker.com/build/building/context/#local-context).
+
+For example:
+```json
+{
+    "version": "1.0",
+    "services": {
+        "web": {
+            "port": 8080,
+            "command": "./bin/serve.sh",
+            "image": "webimage"
+        }
+    },
+    "images": {
+        "webimage": {
+            "dockerfile": "webapp/Dockerfile",
+            "context": "webapp/."
+        }
+    }
+}
+```
+or another exmaple, if the Dockerfile is in a sub-directory, but should be built using the root as the context:
+```json
+{
+    "version": "1.0",
+    "services": {
+        "web": {
+            "port": 8080,
+            "command": "./bin/serve.sh",
+            "image": "webimage"
+        }
+    },
+    "images": {
+        "webimage": {
+            "dockerfile": "webapp/Dockerfile",
+            "context": "."
+        }
+    }
+}
+```
+
+## Using Publicly Downloadable Images
+
+If the name of the image to use is not defined in `images`, Disco will see if it can download it.
+
+```json
+{
+    "version": "1.0",
+    "services": {
+        "worker": {
+            "command": "python -c $'import time\nwhile True:\n time.sleep(1)'",
+            "image": "python:3.12.3"
+        }
+    }
+}
+```
+
+In this case, it would use the [official Python image](https://hub.docker.com/_/python) from Docker Hub.
+
+It's the equivalent of running
+```bash
+docker pull python:3.12.3
+docker run python:3.12.3 python -c $'import time\nwhile True:\n time.sleep(1)'
+```