Publishing Dendron as an Azure Static Web App

How to publish Dendron as an Azure Static Web App on the current Preview service.

To do this, you will need:

A Dendron workspace with some notes you want to publish
A Github account and repository
A Microsoft Azure account
(Optional) A custom domain or subdomain for your notes

At the moment, Azure Static Web Apps is in preview and only supports Github repositories. Before you begin, push your files to a Github repo as we'll be using that later on. This guide assumes you've created your Git repo at the root of your Dendron workspace (i.e. in the same folder that you find your dendron.yml file). Be aware that if you do not configure any routes on the Static Web App it will be publicly available on the internet, even if the Github repo is private.

Basic method

This is the simple method for publishing a Dendron app which doesn't take full advantage of all of the automation available. With this approach you must build your dendron site locally before you will see changes online.

For Dendron 0.32 and below: You'll see a gemfile and a _config.yaml file in the root of your build folder. These interfere with the Azure build process as it mistakes them for a Ruby app and tries to build them. These are left over from an older Dendron publishing method and can safely be deleted. You must do this before you push the folder to Github for Azure publishing to work properly.

Go to your Azure Portal. If you see "Static Web Apps" in the Create a resource panel, you can use that, otherwise click "More services" and then search for "Static Web Apps" there. Click that and the list of your existing static web apps appears, which is probably none.
Create a new static web app using the "+ Add" button. The next page is a form where you can fill in everything (hopefully) necessary to get your app published.
1. Choose your subscription (i.e. how you'll pay for any costs) and the resource group within that subscription.
2. Choose a name for your app (it has to be unique in your organisation) and the region you want it hosted in. You probably want to choose the region closest to you.
3. Use the button to connect to and authorise Azure to access your Github account. Choose the repository and branch where you files are stored.
4. Under "Build Details", choose Custom for Build Presets, /docs for App Location and make sure API Location and Output Location are blank.
5. Click the Review + Create button and you should get a summary screen with all your info.
6. Make sure you're happy with everything and click Create.
If all goes well you should have successfully create the Azure side of things. Take a look at the Essentials info at the top of the app's page and it should show you your URL. The process will have created a Github workflow in ./github/workflows with the same name. It doesn't delete this if you delete the Azure web app, so watch out for that!
Set up your web address for the build.
1. Take a note of the URL and copy it into the SiteUrl: property of your dendron.yml file.
2. OR, to use a custom domain/subdomain, create a cname to point to the Azure URL has given you.
  1. If you wanted to host your vault at vault.mydomain.com you'd want to create a cname for "vault" with your DNS host that points to the URL Azure has given you (something-something.azurestaticapps.com).
  2. You'll also need to verify this domain on the Azure portal if you haven't done so before. Go to the "Custom Domains" section o your Static Web App and add the domain you want to use for the app, then go through the verification steps.
3. Run Dendron: Site Build in VSCode.
4. Commit and push the files created to your Github repo.
With a minute or two your Dendron vault should appear on the URL you've chosen. Congratulations, you've published your notes on Azure Web Apps!

Troubleshooting:

The Static Web Apps deployment process runs a Github workflow. It's the Actions tab of your Github repo that you'll find most errors.
Visit the URL you expect the site to appear on - Azure is fairly good at sensible error messages there.

Secure publication

At the moment there isn't any authorisation and authentication built into Dendron. With a bit of fiddling you can use Azure Web Apps to secure your Dendron vault so only those you want can get access. We do this by building Dendron into a subfolder of the Azure app. Azure Static Web Apps will always serve the index.html file in the root of your app to everyone without any authentication. So what we'll do is create a new index.html as a landing page, moving Dendron's index.html into a subfolder called "vault".

If you've run "site build" before you might want to empty the "docs" output directory so you're starting from a clean build.

In your dendron.yml file add/edit the values:

    siteRootDir: docs/vault
    assetsPrefix: vault

Create a file called staticwebapp.config.json in the root of your app directory ("docs" in our example) with the following content. This will mean that only people with the "authenticated" role can see anything in "vault".

{
    "routes": [
        {
            "route": "/vault/*",
            "allowedRoles": ["authenticated"]
        },       
    ]
}

Run the build and you should see that you've got the normal "docs" folder, but it's empty except for a folder called "vault" where your published vault lives.

Create a new index.html file in the app root, "docs" folder, replacing "notes.mydomain.com" with the URL of your site.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Document</title>
</head>
<body>
    <h1>Dendron Vault login</h1>
    <p>
        <ul>
            <li><a href="https://notes.mydomain.com/.auth/login/aad">Azure AD</a></li>
            <li><a href="https://notes.mydomain.com/.auth/login/github">GitHub</a></li>
            <li><a href="https://notes.mydomain.com/.auth/login/facebook">Facebook</a></li>
            <li><a href="https://notes.mydomain.com/.auth/login/google">Google</a></li>
            <li><a href="https://notes.mydomain.com/.auth/login/twitter">Twitter</a></li>
        </ul>
    <a href="vault/">View notes</a>
    <br>
    <a href="https://notes.mydomain.com/.auth/logout"></a>
    </p>
</body>
</html>

Add people you want to be able to access the notes to the appropriate roles in the Azure portal. Once that's done, they'll be able to log in on the index page and then access the contents of the vault. Everyone else will get a 401 response.

Basic method

Secure publication