Skip to content

DigitalOcean App Platform

Last updated: 21st December 2021

DigitalOcean App Platform offers quick build and deployment from GitHub, GitLab, or Bitbucket.

This post walks through deploying an MkDocs site with the Material theme.

There are some differences between deploying a site with the free Material theme, and one using Material Insiders (accessible to sponsors). This guide covers both.

Prerequisites

I've assumed you:

  • Have an MkDocs site using the Material theme
  • Are using GitHub as your remote repo (but the process should be very similar for GitLab or Bitbucket)
  • Have a DigitalOcean account
  • If you are using Insiders, you have set up a personal access token.

Site setup

Add these files to the root of your project:

  • A runtime.txt to set your Python version. For example: 
    1
    python-3.10.1
    Make sure you use one of the supported Python versions.

  • Either a requirements.txt, Pipfile, or setup.py, so that DigitalOcean can recognise your project as a Python app. For an MkDocs site, the simplest option is a requirements.txt file.

    For the free theme:

    1
2
    mkdocs-material==<YOUR_MATERIAL_VERSION>
# any other dependencies

    For the Insiders theme, you must still create an empty requirements.txt, even if you have no other dependencies.

Note

If you are using a monorepo pattern, note that the files must be in the root of the entire repo, not just the root of your MkDocs project.

Deployment

  1. In your DigitalOcean dashboard, select Create > Apps.
  2. Select GitHub. If this is your first time using App Platform, it will take you through an authentication process with GitHub. Make sure you allow access to the repo you want to deploy. Once GitHub is connected, DigitalOcean shows the Choose Source screen.
  3. Choose the repository you want to deploy.
  4. Select the branch you want to deploy, and choose whether to autodeploy changes. Select Next.
  5. On Configure your app, enter the build settings:
    • Source Directory: if your repo only contains one site, leave this as /. If you have a monorepo (multiple sites/apps in one repo), choose the directory containing you MkDocs site.
    • Type: select Static Site.
    • Environment Variables: if you are using Insiders, create an environment variable named GH_TOKEN, with your personal access token as the value. Select Encrypt to encrypt the value, meaning no-one can access the value of the GitHub token through the dashboard.
    • Build Command:
      • For the free theme: mkdocs build.
      • For the Insider theme: 
        1
        pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git p && mkdocs build
    • Output Directory: site, or the value of site_dir if your site uses a custom output directory name.
    • Leave HTTP Request Routes as its default, and don't add a database.
  6. Select Next.
  7. Enter a name for your site. Select Next.
  8. DigitalOcean automatically selects the starter plan for this type of project. It's designed for testing, and allows you to create three sites for free. Sadly, it won't permit you to choose a higher plan.
  9. Select Launch Starter App. DigitalOcean builds and deploys your site, providing a default URL so you can immediately view the live site as soon as the build finishes.

For guidance on next steps, including adding a custom domain, refer to the documentation.

Hire me for a docs consultation