Hadron Logo

Setup | Skeleton

This guide walks you through setting up the Hadron Skeleton. It explains which changes should be made after installation to create an optimized website.

Expert Setup Skeleton

Important

These docs are compatible only with Hadron v3, using Grav v2 & Quark2, as there are significant changes in structure and functionality.

You can find the Hadron v2 Documentation either on the Wayback Machine or on the GitHub Repository.

Tip

Follow this step-by-step guide which describes how we at Crabston GmbH create and configure websites for our clients using the Hadron Skeleton.

0. Preparation

  1. Fork the skeleton repository / create from template
  2. Clone the repository including Grav: 
    cd /your/preferred/directory
git clone https://github.com/Crabston/grav.git .
git clone https://github.com/Crabston/grav-skeleton-hadron.git user

Note

See the Hadron Skeleton installation guide for additional cloning methods and alternatives.

0.1 SendGrid API Key

SendGrid is an email service provider that enables sending email. You need an account with SendGrid for this.

Once a basic configuration exists, create a new API key at app.sendgrid.com/settings/api_keys with the permission Mail Send (Mail Send: Yes). Add the key to your configuration or manage it via Doppler.

0.2 Umami Website ID

Umami Analytics is an open-source analytics tool for collecting detailed website statistics. You need an account on Umami or access to a hosting server.

Create a new site/project in Umami and copy the website ID. Then add the website ID in the Umami configuration or manage it via Doppler.

0.3 Doppler configuration

Doppler is a secrets manager for securely storing and managing API keys and other sensitive data. You need a Doppler account for this.

Create a new project in Doppler, then add the following secrets:

  • SENDGRID_API_KEY: API_KEY_VALUE: plugins.email_DASH_sendgrid.api_key
  • UMAMI_WEBSITE_ID: WEBSITE_ID_VALUE: plugins.umami_DASH_analytics.website_id

The list above is in the format SECRET_NAME: SECRET_VALUE: SECRET_PATH. SECRET_NAME is the secret's name, SECRET_VALUE is its value and SECRET_PATH is the path where the secret is used. Add SECRET_PATH as a note in Doppler.

After adding the secrets, update the Doppler configuration file doppler.yaml:

setup:
    project: PROJECT_NAME
    config: prd

1. Formal changes

Formal changes include small administrative adjustments that are not directly related to the website content but are practical. This affects the following files:

  1. README.md: Update the readme to store key information about the site
  2. LICENSE: Add the correct license file
  3. CHANGELOG.md: Update the changelog to document site changes

For convenience, you can version these administrative changes directly (e.g. on GitHub) before cloning the repository.

2. Base configuration

With the Grav base configuration you can apply well-known changes before installation so you can start fine-tuning after installation.

Tip

Find more information about a local development environment here: Documentation / Skeleton / Development Environment

  1. If user accounts already exist, create or copy them
  2. If you already know which plugins and themes you want to use, add or remove them in the .dependencies file
  3. Afterwards you can adjust system and site settings
  4. Finally, you can make individual changes to plugin and theme configurations

At this point it's worth creating a new Git branch and making at least one commit per configuration/chapter.

2.1 Accounts

If user accounts already exist they can be created. Create one file per account in user/accounts. The file must have the following structure:

accounts/username.yaml:

state: enabled
email: email@example.com
fullname: User's full name
title: User's title
hashed_password: HASHED_PASSWORD
admin_next:
    preferences:
        adminLanguage: en-US # Language
access: # ... individual access permissions (if not handled via groups)
    api:
        login: true # Admin login
        super: true # Super user
    site:
        login: true # Site login
groups: # List of groups
    - website     # Can log in to the website and view protected pages
    - admin       # Can log in to the admin panel and access the API
    - accounts    # Can manage user accounts and groups
    - editor      # Can edit content on the site, including pages and media
    - maintainer  # Can manage restricted parts of the site & see relevant system information
    - manager     # Can manage the site as a whole themselves. DO ONLY GRANT TO TRAINED & EXPERIENCED USERS!
    - statistics  # Can see site statistics

2.2 Dependencies

Use the .dependencies file to install required plugins and themes via the built-in function. Adjust it: remove unwanted plugins/themes and add the ones you need.

2.3 Settings

There are two main configuration files you should adjust. Recommended edits include:

config/site.yaml:

title: 'Site name'
default_lang: en # Default language
author:
    name: 'Default author / organization'
    email: contact@example.com
metadata:
    description: 'Default site description'
    keywords: 'relevant, keywords, for, the, site'
blog:
    route: '/blog'

config/system.yaml:

timezone: Europe/Zurich # Server / site timezone
custom_base_url: https://usehadron.dev/ # Base URL
languages:
    supported: # List supported languages
        - en
default_lang: en # Default language
home:
    alias: /home # Path of the homepage
pages:
    theme: custom # Theme to use

2.4 Theme & plugins

You can already make the following changes to themes and plugins:

config/themes/custom.yaml: See Documentation / Theme / Options

config/plugins/email.yaml:

from: your@provider.mail # Default sender (SendGrid by default)
to: contact@example.com  # Default recipient

config/plugins/feed.yaml:

title: 'Feed name'
description: 'Feed description'

config/plugins/sitemap.yaml:

news_enabled_paths:
    - /blog

config/plugins/taxonomylist.yaml:

route: /blog

config/plugins/umami-analytics.yaml:

script_src: 'https://umami.crabston.ch'   # Umami host URL
website_id: 'UMAMI_WEBSITE_ID'            # Website ID if not provided via Doppler
domains: 'example.com'                    # Domains that may send data, separated by commas

3. Installation

After the base configuration is ready, install Grav and start the server if necessary.

bin/grav install
bin/plugin tntsearch index
bin/grav server

Open the site locally at http://127.0.0.1:8000. If no accounts exist yet, create the admin account at http://127.0.0.1:8000/admin. You can then view the skeleton's default pages or make further adjustments via the admin panel.

4. Further adjustments

You can now adjust more settings, extend the custom theme and create or edit new pages.

config/theme/custom.yaml:

# Logo configuration
favicon:
    user/media/favicon/hadron-favicon.svg:
        name: hadron-favicon.svg
        type: image/svg+xml
        size: 566
        path: user/media/favicon/hadron-favicon.svg
custom_logo:
    user/media/logo/hadron-logo.svg:
        name: hadron-logo.svg
        type: image/svg+xml
        size: 3076
        path: user/media/logo/hadron-logo.svg
custom_logo_mobile:
    user/media/logo/hadron-logo.svg:
        name: hadron-logo.svg
        type: image/svg+xml
        size: 3076
        path: user/media/logo/hadron-logo.svg