Configuring and Installing GatorSmile CMS

Sunday, 24 July 2022
  • By
  • Jeff Ammons
  • Tags:
  • Blogging
  • Blog
  • CMS
  • Programming
  • Projects
  • .NET
  • C#

Alligator crusing along with a vine on his back

How difficult could it be???

This post is meant to help me keep track of the steps I need to follow to set up a new GatorSmile based website.

I've only set up one site (this one) so far, so now I'm ready to set up my creative outlet site GalacticBeacon.

In this post, I'll record the steps I have to go through to get it done.

Basic Starter

So the basic starter flow for GatorSmile is this:

  1. Clone the GatorSmile repo. You'll clone this both locally where you want to work and onto your VM where you want to deploy it. NOTE: as of this post I haven't made this public yet. Until I get it farther along and more user friendly, I'll keep it private.
  2. Create a Repo for your content
  3. Clone the content repo into your GatorSmile/ReaderWebUI as wwwroot. NOTE: Supremely important that you get this right and it becomes the wwwroot directory. git clone MYREPO wwwroot
  4. For the ReaderWebUI project you will want to use Manage User Secrets to add an entry for your reload key. Example: "ReloadToken": "ABC123-COULD-BE-ANYTHING-YOU-LIKE"

I'll make another post later that goes through what should be in the content repo, but it includes these directories:

  • Posts: Markdown and YAML post files
  • Views: Your CSHTML files with Razor views
  • Config: Your json configuration files with meta data about your site
  • CSS: Your style sheets
  • JS: Your JavaScript files
  • Lib: Client side libraries like Bootstrap

Running Locally

Once you have the basics set up, you can run the site locally to test and add content.

I will either load the GatorSmile solution in Visual Studio and run the ReaderWebUI project from there or use the dotnet CLI to run it.

If I'm working on adding a feature to GatorSmile I'll use Visual Studio. If I'm writing content, then I'll just use Visual Studio Code and do dotnet run in the integrated terminal.

I also keep the VS Code View Markdown pane open while I'm writing.

In my _layout view I keed code to add a reload content button when I'm in my dev environment.

@if (meta.IsDevelopment)
    <a href="/api/admin/UpdateContent?submittedToken=@meta.ReloadToken">Reload Content</a>

I pack a lot into the meta data object so that you can do quite a lot in the CSHTML without changing the GatorSmile code.

Publishing to VM

You could totally run this in a variety of places and ways.

You could set up Azure DevOps and deploy directly to Azure App services.

You could put it in a container and deploy it wherever fine containers are deployed.

For simplicity (and because I am, for lack of a better word, cheap), I run on a simple Linux VM.

Since ASP.NET won't see your View changes without compiling, you need a compile step in there if you change your views.

I just clone everything into directories on my VM, then use the dotnet CLI to build and publish.

If you just simple make changes to your content, then you don't need the compile step. In fact you can set up a webhook to trigger on pushes to use git to update your content repository and reload the data automatically.

I haven't done it yet, but I am going to write a script on the VM to build and publish any of my sites. For now I do it manually via the terminal and SSH.

Configuring the VM

This section is really specific to me and how I like to set things up. Your mileage may vary. Scratch that, it WILL vary depending on how you like to set up.

  1. Configure Nginx if you haven't already
    • Create a directory
    • Add config to /etc/nginx/sites-available
  2. Configure dotnet to run your site
    • Add it to whatever runs automatically in your OS, for me it is systemctl
  3. Point your DNS at your VM
  4. Add a cert to enable HTTPS
    • I use Let's Encrypt because it's free and on Linux at least very easy to use
  5. Add a webhook in your Git Hosting service to let your GatorSmile site know when things change (I use GitHub)
    • You will need to create a key that will be passed from the source host whenever you push changes

Adding a GitHub Webhook to Update Your Content When You Push to the Repo

How cool would it be if your blog updated when you pushed to your GitHub repo?

  • Generate a new SSH key
  • Create a Deploy Key with that SSH Key
  • Either clone the repository using that key or
  • Change the local repo config to use that key
  • Create a Webhook on GitHub
  • Generate a GUID for the webhook secret
  • Add the webhook secret as an environment variable on your server

This isn't a complete list and is very much a working document.

When I'm ready to make GatorSmile public, much of this will move into the GitHub repo README and wiki.