README.qmd

Diligent Services Quarto Project

This site was created using Quarto, an open-source scientific and technical publishing system. Below you will find detailed information about the project structure and how to update the site.

Project Structure

The repository contains the following main files and directories:

  • _quarto.yml: Main configuration file.
  • index.qmd: Main page.
  • about.qmd: About page.
  • contact.qmd: Contact page.
  • styles/custom.scss: Custom styles.
  • blog/*: Blog posts.
  • images/logo.png: Company logo.
  • _site/: Generated site files (ignored in Git).
  • .gitignore: Git ignore file to exclude unnecessary files.
  • cloud-config.yaml: Cloud-init script for initial server setup.
  • README_.qmd: This file, providing meta information about the project.

Attribution

This site was created using Quarto, an open-source scientific and technical publishing system developed and maintained by RStudio, PBC and the open-source community.

Learn more about Quarto at quarto.org.

License

This project is licensed under the Creative Commons Attribution 4.0 International (CC BY 4.0) license. You are free to copy, modify, and distribute this work, provided you give appropriate credit.

Learn more about the license at creativecommons.org/licenses/by/4.0.

Hosting and Domain

This site is hosted on a basic Hetnzer instance, and the domain is managed by Namecheap. Neither Hetnzer nor Namecheap are paid sponsors, but I really like their product.

Transparency and Readme

This README describes exactly what this repository is and what it contains. The site points to the repo in an effort to be as transparent as possible in everything we build, from websites, to construction projects, to business strategies. The README_.qmd file is symbolically linked to README.qmd to keep them synced.

Setup and Deployment

Prerequisites

Initial Server Setup

  1. Generate SSH Key (if you don’t have one):

    ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

  2. Add SSH Key to SSH Agent:

    eval "$(ssh-agent -s)"
ssh-add ~/.ssh/ssgh.pem

  3. Set Correct Permissions:

    chmod 600 ~/.ssh/ssgh.pem

  4. Add SSH Key to GitHub:

    cat ~/.ssh/ssgh.pem.pub

  5. Verify SSH Connection to GitHub:

    ssh -i ~/.ssh/ssgh.pem -T git@github.com

    You should see a message like:

    Hi <USERNAME>! You've successfully authenticated, but GitHub does not provide shell access.

  6. Configure SSH to Use the Specific Key:

    vim ~/.ssh/config

    Add the following configuration:

    Host github.com
HostName github.com
User git
IdentityFile ~/.ssh/ssgh.pem

    Save and exit the file (:wq writes, then quits vim. you heard it here again).

  7. Clone the Repository on the Server:

    cd /var/www/<SITENAME>
git clone git@github.com:<USERNAME>/<REPONAME>.git

  8. Obtain SSL Certificates:

    sudo certbot certonly --webroot -w /var/www/<SITENAME>/<REPONAME>/_site -d <SITENAME.TLD> -d www.<SITENAME.TLD>

Local Development

  1. Clone the Repository Locally:

    git clone git@github.com:<USERNAME>/<REPONAME>.git
cd <REPONAME>

  2. Edit Content and Styles:

    • Edit .qmd files to change content.
    • Edit styles/custom.scss for custom styles.
    • Add images to the images/ directory.

  3. Generate the Site Locally:

    quarto render

  4. Commit and Push Changes to GitHub:

    git add .
git commit -m "Updated content and styles"
git push origin main

Updating the Site on the Server

  1. SSH into the Server:

    ssh -i ~/.ssh/ssgh.pem root@your_server_ip

  2. Navigate to the Project Directory:

    cd /var/www/<SITENAME>/<REPONAME>

  3. Pull the Latest Changes from GitHub:

    git pull origin main

  4. Generate the Site on the Server:

    quarto render

    You should see output like:

    [1/6] contact.qmd
[2/6] index.qmd
[3/6] about.qmd
[4/6] <REPONAME>/contact.qmd
[5/6] <REPONAME>/index.qmd
[6/6] <REPONAME>/about.qmd

Output created: _site/index.html

  5. Reload Nginx to Apply Changes:

    sudo systemctl reload nginx

Nginx Folder Structure

  • /etc/nginx/nginx.conf: Main Nginx configuration file.
  • /etc/nginx/sites-available/<SITENAME>: Site-specific Nginx configuration file.
  • /etc/nginx/sites-enabled/<SITENAME>: Symlink to the site-specific configuration file.
  • /var/www/<SITENAME>/: Directory containing the website files.
  • /var/www/<SITENAME>/<REPONAME>/_site/: Directory containing the generated site files.

GitHub Folder Structure

  • <REPONAME>/: Root directory of the Quarto project.
  • <REPONAME>/_quarto.yml: Quarto configuration file.
  • <REPONAME>/index.qmd: Main page content.
  • <REPONAME>/about.qmd: About page content.
  • <REPONAME>/contact.qmd: Contact page content.
  • <REPONAME>/styles/custom.scss: Custom CSS styles.
  • <REPONAME>/images/logo.png: Company logo image.
  • <REPONAME>/_site/: Generated site files.
  • <REPONAME>/.gitignore: Git ignore file.
  • <REPONAME>/cloud-config.yaml: Cloud-init script.
  • <REPONAME>/README.qmd: This meta explanation file.

Customization

  • Edit .qmd files to change content.
  • Edit styles/custom.scss for custom styles.
  • Add images to the images/ directory.