Add docs for static site generators

letsdiscodev · Jun 23, 2024 · aef130e · aef130e
1 parent a3533dc
commit aef130e
Show file tree

Hide file tree

Showing 3 changed files with 151 additions and 10 deletions.
diff --git a/docs/get-started/set-up-your-app.md b/docs/get-started/set-up-your-app.md
@@ -10,7 +10,7 @@ In this docs you will learn the basics to get your existing app running on Disco
 
 At this point, you already have installed the CLI on your computer, installed Disco on your server, and you have added your Disco Github app with the permissions to your repository on Github.
 
-In this guide, you will have a `Dockerfile` to build the image of your app, and you'll have a `disco.json` file describing how the app should run on Disco.
+After this guide, you will have a `Dockerfile` to build the image of your app, and you'll have a `disco.json` file describing how the app should run on Disco.
 
 ### The app before Disco
 
@@ -75,7 +75,7 @@ See [notes below](#optimizing-the-dockerfile) for some optimizations we can make
 
 ### Create your disco.json
 
-The `disco.json` file tells Disco how to run your app.
+Create a file named `disco.json` at the root of your repository. The `disco.json` file tells Disco how to run your app.
 
 One note is that services have to be accessible from the outside. See [Externally Visible Server](https://flask.palletsprojects.com/en/3.0.x/quickstart/#public-server) in Flask's docs. While the flag `--host=0.0.0.0` is Flask specific, the concept applies to most apps: it may bind to `127.0.0.1` (`localhost`) by default, meaning only requests coming from "inside" would be able to reach the app. This is a great default for developping on your computer, but to deploy your application, it needs to be accessible from the outside, so that the reverse proxy in front of your app can talk to it.
 
@@ -134,4 +134,4 @@ COPY ./requirements.txt /app/requirements.txt
 RUN pip install -r requirements.txt
 # then copy the rest of the app
 COPY . /app
-```
+```
diff --git a/docs/get-started/set-up-your-static-site-generator-site.md b/docs/get-started/set-up-your-static-site-generator-site.md
@@ -0,0 +1,146 @@
+---
+sidebar_position: 6
+---
+
+# Set up your App
+
+In this docs you will learn the basics to get your existing static site generator site building on Disco and being served by Disco. If you have a static site or running apps, refer to these sections instead.
+
+## Overview
+
+At this point, you already have installed the CLI on your computer, installed Disco on your server, and you have added your Disco Github app with the permissions to your repository on Github.
+
+In this guide, you will have a `Dockerfile` to build your site, and you'll have a `disco.json` file telling Disco where to find the files to be served within your image.
+
+### The site before Disco
+
+Let's use a very barebone home made site generator as an example.
+
+The repository contains two files:
+
+```
+generate.py
+requirements.txt
+```
+
+The file `requirements.txt` contains our dependencies:
+```
+markdown2==2.4.13
+```
+
+You would install those dependencies locally with:
+```bash
+pip install -r requirements.txt
+```
+
+The file `generate.py` contains the code to generate our site:
+
+```python
+import os
+import markdown2
+
+DIST_DIR = "dist"
+INDEX_MARKDOWN = """
+# Home
+
+Hello World
+
+"""
+
+html = f"""<!DOCTYPE html>
+<html>
+<head>
+<meta charset="utf-8">
+</head>
+<body>
+    {markdown2.markdown(md)}
+</body>
+</html>
+"""
+
+if not os.path.isdir(DIST_DIR):
+    os.makedirs(DIST_DIR)
+
+with open(f"{DIST_DIR}/index.html", "w", encoding="utf-8") as f:
+    f.write(html)
+```
+
+You could run it locally with:
+```bash
+python generate.py
+```
+
+### Create your Dockerfile
+
+Static sites generator on Disco are built using a `Dockerfile`. 
+
+For this example, in Python, we'll use the official Python image from Docker Hub. Just create a file named `Dockerfile` at the root of your repository.
+
+```Dockerfile
+FROM python:3.12.3
+WORKDIR /site
+COPY . /site
+RUN pip install -r requirements.txt
+RUN python generate.py
+```
+
+See [notes below](#optimizing-the-dockerfile) for some optimizations we can make to speed up builds.
+
+### Create your disco.json
+
+Create a file named `disco.json` at the root of your repository. The `disco.json` file tells Disco where to find the files to serve inside the Docker image we just built with the `Dockerfile` above.
+
+```json
+{
+    "version": "1.0",
+    "services": {
+        "web": {
+            "type": "generator",
+            "publicPath": "dist"
+        }
+    }
+}```
+
+The name `web` is a magic name. When Disco sees it, it knows that it's the one to use to expose to the internet, create a TLS certificate for HTTPS, etc.
+
+`publicPath` is relative to the `WOKRDIR` in your `Dockerfile`. In our example, the directory `dist` actually means `/app/dist` in our Docker image.
+
+
+### That's it!
+
+Your site is now ready to be deployed on Disco. You can use the CLI to add the project.
+
+```bash
+disco projects:add \
+    --name first-site \
+    --github yourname/reponame \
+    --domain first-site.example.com
+```
+
+And now, every time you `git push` new commits, Disco will deploy the site automatically.
+
+You can see the deployment output with:
+```bash
+disco deploy:output --project first-site
+```
+
+### Optimizing the Dockerfile
+
+In the section [Create your Dockerfile](#create-your-dockerfile), to keep it simpler, we just copied the whole app to the image and then installed the dependencies.
+
+While it works, we're not using Docker's build cache to its full extend. When we're copying files to a Docker image, Docker will use the fact that files changed or not to decide if it needs to execute that part of the `Dockerfile`. In other words, if we copy the whole app to the image, chances are that every time we deploy, something changed and we'll go through the whole build.
+
+If we start by copying files that are less likely to change and have a big impact on build time, we can speed up builds quite a bit. In our case, if we copy the `requirements.txt` file first, and install the dependencies, it means that each time we deploy, if nothing changed in `requirements.txt`, Docker will just use the dependencies from the cache and not try to download them again.
+
+```Dockerfile
+FROM python:3.12.3
+WORKDIR /site
+# copy the files describing our dependencies first
+COPY ./requirements.txt /site/requirements.txt
+# install the dependencies
+RUN pip install -r requirements.txt
+# then copy the rest of the site
+COPY . /site
+# then build your site
+RUN python generate.py
+```
diff --git a/docs/get-started/set-up-your-static-site.md b/docs/get-started/set-up-your-static-site.md
@@ -38,7 +38,7 @@ public
 
 ### Create your disco.json
 
-The `disco.json` file tells Disco where to find your files.
+Create a file named `disco.json` at the root of your repository. The `disco.json` file tells Disco where to find your files.
 
 ```json
 {
@@ -71,12 +71,7 @@ And now, every time you `git push` new commits, Disco will deploy the site autom
 
 You can see the deployment output with:
 ```bash
-disco deploy:output --project first-app
-```
-
-And you can stream the logs of your app with:
-```bash
-disco logs --project first-app
+disco deploy:output --project first-site
 ```
 
 ### Security Considerations