<![CDATA[Jay George]]> – Blog / Statamic https://jaygeorge.co.uk/blog Thoughts and tutorials about web design. en https://jaygeorge.co.uk <![CDATA[Making a Podcast Website in Statamic]]> https://jaygeorge.co.uk/blog/making-a-podcast-website-in-statamic https://jaygeorge.co.uk/blog/making-a-podcast-website-in-statamic Making a podcast website is the same as a regular website when you break it down—the big difference is you need to output what's essentially an RSS feed. In this video, we'll build a podcast website in Statamic complete with an Apple podcast feed from scratch.

Most of the video will cover spinning up a site and setting up blueprints. For the written article, here are the things you need to output for the RSS feed, which you'll need to give your podcast host.

1. Output a Link to a Podcast RSS Feed in Your <Head>

Add this to your head.antlers.html:

{{# RSS
=================================================== #}}
<link rel="alternate" type="application/rss+xml" title="Name of your podcast feed" href="{{ current_url }}/rss">

2. Create an RSS Template

Create a new file at resources/views/rss.antlers.html. Here is my specific implementation:

{{ xml_header }}

<rss xmlns:itunes="http://www.itunes.com/dtds/podcast-1.0.dtd" version="2.0">
    <channel>
        <title>{{ brand:name | cdata }}</title>
        <itunes:title>{{ brand:name | cdata }}</itunes:title>
        <link>{{ config:app:url }}</link>
        <language>en-us</language>
        <copyright>{{ brand:authors | cdata }}</copyright>
        <itunes:author>{{ brand:authors | cdata }}</itunes:author>
        <itunes:summary>{{ brand:podcast_description | cdata }}</itunes:summary>
        {{# This should hold a concise, one-sentence description of your podcast. #}}
        <itunes:subtitle>{{ brand:podcast_subtitle | cdata }}</itunes:subtitle>
        <itunes:explicit>yes</itunes:explicit>
        <description>{{ brand:podcast_description | cdata }}</description>
        <itunes:owner>
            <itunes:name>{{ brand:podcast_owner | cdata }}</itunes:name>
            <itunes:email>{{ brand:podcast_email | cdata }}</itunes:email>
        </itunes:owner>
        <itunes:image href="{{ config:app:url }}{{ glide:brand:podcast_artwork square='1400' }}" />
        <itunes:keywords>Games</itunes:keywords>
        {{# https://www.podcastinsights.com/itunes-podcast-categories/ #}}
        <itunes:category text="Leisure">
            <itunes:category text="Video Games" />
        </itunes:category>
        <itunes:category text="News">
            <itunes:category text="Tech News" />
        </itunes:category>
        <itunes:category text="Technology"/>

        {{# PODCAST
        =================================================== #}}
        {{ collection:episodes as='posts' sort='date:desc' }}
            {{ partial:rss-post }}
        {{ /collection:episodes }}
    </channel>
</rss>

In the above we're linking to an item partial, which looks like this:

{{ posts }}
    <item>
        <title>Ep.{{ episode_number | cdata }} {{ title | cdata }}</title>
        <link>{{ config:app:url }}/episodes/{{ episode_number }}-{{ slug }}</link>
        <itunes:author>{{ brand:authors | cdata }}</itunes:author>
        <itunes:explicit>yes</itunes:explicit>
        <itunes:subtitle>{{ content | smartypants | striptags | cdata }}</itunes:subtitle>
        <itunes:summary>{{ content | smartypants | striptags | cdata }}</itunes:summary>
        {{# the Description tag is requested by some hosts e.g. https://podcasters.radiopublic.com/dashboard #}}
        <description>{{ content | smartypants | striptags | cdata }}</description>
        <itunes:image href="{{ config:app:url }}{{ if artwork }}{{ glide:artwork square='1400' }}{{ else }}{{ glide:brand:podcast_artwork square='1400' }}{{ /if }}" />
        <enclosure url="{{ audio }}" length="{{ size }}" type="audio/mpeg" />
        <guid>{{ episode_number }}</guid>
        <pubDate>{{ date format='D, d M Y H:i:s O' }}</pubDate>
        <itunes:duration>{{ duration }}</itunes:duration>
    </item>
{{ /posts }}

3. Create a Route

We need to define a route which removes the layout template and processes. Open routes/web.php and add the following: Route::statamic('/rss', 'rss', ['layout' => '', 'content_type' => 'xml']);

What we're saying here is—When these routes are matched, use our 'rss' Antler's template, skip layout processing (you'll notice we have a blank layout argument), then render the content as 'xml'—which is needed for podcast feeds.

4. Validate Your Podcast Feed

Podcast aggregators are fussy about how they receive content so it's best to be thorough. My favourites are Cast Feed Validator and Podbase

]]>
Mon, 12 Apr 2021 00:00:00 +0000
<![CDATA[Serving Multiple RSS Feeds in Statamic]]> https://jaygeorge.co.uk/blog/serving-multiple-rss-feeds-in-statamic https://jaygeorge.co.uk/blog/serving-multiple-rss-feeds-in-statamic When it comes to RSS, it’s more tempting to subscribe to a feed when it's exactly what you want. For example, what if you want to subscribe to BBC News, but you don't really care for politics? Luckily bigger websites often provide multiple “sub” feeds so you can subscribe to specific topics rather than everything under the sun.

What if you want to offer multiple feeds on your own site? I was stuck with this question—since I write about a variety of things. I write music reviews, film reviews, posts about Statamic, and thought-pieces. I know not everyone cares for my music taste, so I decided to figure out how to offer different RSS feeds using Statamic since this is what my site is currently built on.

The result is my Subscribe page, where I've output all the possible RSS feeds on this site so fellow RSS-lovers can pick and choose. So how did I do this?

1. Conditionally Output an RSS Title in Your <head>

Adding a link to the head means that visitors can just dump the page URL in an RSS reader and it'll fetch the feed automatically. The minimum amount of code you’d need to link to an RSS feed would be like this:

<link rel="alternate" type="application/rss+xml" title="Jay's Blog feed" href="{{ current_url }}/rss">

This would work well for a blog, for example.

But since we want to offer different feed titles depending on the page, we'll need to use an if statement to understand which page we're on.

We can easily set variables in Statamic at the very top of the antlers file.

At the top of my resources/views/blog/index.antlers.html file I've added:

---
rss: blog
---

Subsequently at the top of my resources/views/listening/index.antlers.html file I have:

---
rss: listening
---

And at the top of my resources/views/watched/index.antlers.html file I have:

---
rss: watched
---

We now want an if statement in our head to detect the page and conditionally serve the relevant feed link. In my case I've broadly split RSS feeds into my Blog, Listening, and Watched. You could probably make this code a little leaner by simply outputting the title dynamically, but I wanted a little more control over the title so this is the way I did it.

{{ if view:rss == "blog" }}
    <link rel="alternate" type="application/rss+xml" title="Jay's Blog" href="{{ current_url }}/rss">
{{ elseif view:rss == "listening" }}
    <link rel="alternate" type="application/rss+xml" title="Jay George &ndash; Intrigue / Listening" href="{{ current_url }}/rss">
{{ elseif view:rss == "watched" }}
    <link rel="alternate" type="application/rss+xml" title="Jay George &ndash; Intrigue / Watched" href="{{ current_url }}/rss">
{{ /if }}

2. Create a Dynamic RSS Template

Create a new file called resources/views/rss.antlers.htmlThis is the file we'll use to generate a dynamic RSS feed depending on the URL. For reference, here is a simple static RSS feed:

<?xml version="1.0" encoding="UTF-8" ?>
<rss version="2.0">

<channel>
  <title>Your Page</title>
  <link>https://yoursite.com/blog</link>
  <description>Name of your blog</description>
  <item>
    <title>RSS Tutorial</title>
    <link>https://somesite.com/xml/xml_rss.asp</link>
    <description>New RSS tutorial on Some Site</description>
  </item>
  <item>
    <title>XML Tutorial</title>
    <link>https://somesite.com/xml</link>
    <description>New XML tutorial on Some Site</description>
  </item>
</channel>

</rss> 

What we need to do instead is dynamically construct a feed by testing the URL “segments”. This is best understood through looking at a code example. Here is my specific implementation. FYI I've used the standard HTML comments syntax here so they stand out a bit more in the example:

{{ xml_header }}

<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
    <channel>
        <!-- Construct RSS link by testing segments -->
        <atom:link href="{{ config:app:url }}/{{ segment_1 }}{{ if segment_2 }}/{{ segment_2 }}{{ /if }}{{ if segment_3 }}/{{ segment_3 }}/rss{{ /if }}" rel="self" type="application/rss+xml" />
        <title>{{ brand:name | cdata }} – {{ segment_1 | title }}{{ if segment_3 }} / {{ segment_3 | title }}{{ /if }}</title>
        <link>{{ config:app:url }}/{{ segment_1 }}</link>
        <description>{{ if segment_1 == 'blog' }}Thoughts and tutorials about web design.{{ /if }}</description>
        <language>en</language>
        <generator>{{ config:app:url }}</generator>

        {{# BLOG
        =================================================== #}}
        <!-- Test segments to determine which collections and taxonomies to pull into the feed -->
        {{ if segment_1 == 'blog' }}
            {{ if segment_3 }}
                {{ if segment_2 == 'categories' }}
                    { collection:blog as='posts' limit='10' taxonomy:categories="{segment_3}" }
                        {{ partial:rss-post }}
                    { /collection:blog }
                {{ elseif segment_2 == 'tags' }}
                    {{ collection:blog as='posts' limit='10' taxonomy:tags="{segment_3}" }}
                        {{ partial:rss-post }}
                    {{ /collection:blog }}
                {{ /if }}
            {{ else }}
                {{ collection:blog as='posts' limit='10' }}
                    {{ partial:rss-post }}
                {{ /collection:blog }}
            {{ /if }}
        {{ /if }}

        {{# LISTENING
        =================================================== #}}
        {{ if segment_1 == 'listening' }}
            {{ collection:listening as='posts' sort="date:desc" limit='10' }}
                {{ partial:rss-post-listening }}
            {{ /collection:listening }}
        {{ /if }}

        {{# WATCHED
        =================================================== #}}
        {{ if segment_1 == 'watched' }}
            {{ collection:watched as='posts' sort="date:desc" limit='10' }}
                {{ partial:rss-post-watched }}
            {{ /collection:watched }}
        {{ /if }}
    </channel>
</rss>

In the above we're linking to partials. As an example, here is the partial that's stored in /resources/views/_rss-post.antlers.html:

{{ posts }}
    <item>
        <title>{{ title | cdata }}</title>
        <link>{{ permalink }}</link>
        <guid >{{ permalink }}</guid>
        <description>
            {{ if hero_image }}
                <![CDATA[<img src="{{ config:app:url }}{{ glide:hero_image width="1920" height="1080" }}" width="1920" height="1080" alt="{{ hero_image:alt }}" />]]>
            {{ /if }}
            {{ main_content }}
                {{ if type == 'text' }}
                    {{ text | full_urls | cdata }}
                {{ elseif type == 'super_blockquote' }}
                    <blockquote>
                        {{ quote | full_urls | cdata }}{{ if attribution }}—{{ if attribution_link }}<a href="{{ attribution_link }}">{{ /if }}{{ attribution }}{{ attribution_link ?= '</a>' }}{{ /if }}
                    </blockquote>
                {{ elseif type == 'inline_image' }}
                    {{ caption ?= '<figure>' }}
                        <![CDATA[<img src="{{ glide:image }}" loading="lazy" width="{{ image }}{{ width }}{{ /image }}" height="{{ image }}{{ height }}{{ /image }}" alt="{{ image:alt }}" />{{ if caption }}<figcaption>{{ caption }}</figcaption>{{ /if }}{{ caption ?= '</figure>' }}]]>
                {{ elseif type == 'full-width_image' }}
                    {{ caption ?= '<figure>' }}
                        <![CDATA[<img src="{{ config:app:url }}{{ glide:image width="860" dpr="2" }}" loading="lazy" width="200" height="200" alt="{{ image:alt ?? caption }}" />{{ if caption }}<figcaption>{{ caption }}</figcaption>{{ /if }}{{ caption ?= '</figure>' }}]]>
                {{ /if }}
            {{ /main_content }}
        </description>
        {{ if categories || tags }}
            {{ if categories }}
                <category>
                    {{ categories }}
                        {{ title | cdata }}
                    {{ /categories }}
                </category>
            {{ /if }}
            {{ if tags }}
                <category>
                    {{ tags }}
                        {{ title | cdata }}
                    {{ /tags }}
                </category>
            {{ /if }}
        {{ /if }}
        <pubDate>{{ date format='D, d M Y H:i:s O' }}</pubDate>
    </item>
{{ /posts }}

3. Create a Route

We need to define a route that removes the layout template and processes since we simply want to output the feed as an 'atom' content type, which is the preferred content type for RSS.

You can create routes with Statamic through routes/web.php. This is the code I have in web.php:

// e.g. /blog/rss or /listening/rss
Route::statamic('{route_dir_1}/rss', 'rss', ['layout' => '', 'content_type' => 'atom']);
// e.g. /blog/categories/business or /blog/tags/dropbox
Route::statamic('{route_dir_1}/{route_dir_2}/{route_dir_3}/rss', 'rss', ['layout' => '', 'content_type' => 'atom']);

What we're saying here is—When these routes are matched, use our 'rss' Antler's template, skip layout processing (you'll notice we have a blank layout argument), then render the content as 'atom'—which is needed for RSS.

Some other things to note:

  • We have two routes in my particular example.

  • The order of the routes matters.

  • Put less specific routes first. If the URL matches the first route, the second route will effectively be ignored.

  • You can name the variables whatever you like, I just went with {route_directory_1}, etc. because it made it easy for me to understand

  • We don't need to do it here but you can reference these route variable names in your templates if you like—although in this case, I find it easier to use the built-in Statamic's built-in {segment} tags

Tidying Up

  1. Remember to clear the route cache, else the route won't work. Use the command php artisan route:clear to do this.

    1. Also, remember to run this command on your next deployment to your production server

  2. Validate your RSS Feed using the W3C validator to check everything is OK.

]]>
Sat, 10 Apr 2021 00:00:00 +0000
<![CDATA[Recommended Ploi Settings for Statamic]]> https://jaygeorge.co.uk/blog/recommended-ploi-settings-for-statamic https://jaygeorge.co.uk/blog/recommended-ploi-settings-for-statamic Below is a list of recommended settings for a Statamic + Ploi workflow. Since I use a couple of different CMS's with Ploi, I've split these into different sections.

General Ploi Settings

  • Click your avatar (top right) > Profile

    • Settings > Theme mode > Dark —I'm not usually a big dark-mode fan but I like it here

    • Backup configurations > configure these as needed

    • Security > Enable 2FA here

  • Server > Select your server > PHP

    • Manage Extensions (button)

      • Imagick (checkbox)

    • Enable OPcache (button). If we're using Statamic and have the default php7.4-fpm reload command in our deploy script, then we don't need to worry about the warning here

Editing File Backups

If you've spent some time setting up file backups (as above) you can edit or run them manually—but the settings are in a different place. Go to Sites > Your Site > Manage > File Backups

Notifications

  • Click your avatar (top right) > Profile

    • Integrations

      • Set this up first with whatever service you'd like. Personally I use Google Drive for backups and Telegram for notifications, so I'll include instructions for them below.

    • Notification Channels

      • For Telegram I chose a label of “Telegram” and clicked “Create”

Setting Up Notifications for Sites

Once you've set up this base configuration you'll need to set up notifications on a site basis.

  • Sites > Your Site > Notifications

    • Select your Telegram setup here from the dropdown

Setting Up Server Notifications

  • Servers > Your Server > Monitoring > add a notification for anything over 80%. There's no basis for this number, but it felt like a good point at which I'd like to take action.

    • While you're here, click the channel notification to also send an alert through Telegram if this happens

  • Server > Manage > Automatic update notifications > choose a service to be notified on e.g. Telegram. I tend to set up automatic server updates on a weekly basis here.

Password Protect a Site

I thought it was worth mentioning how to do this since it's a brilliant feature that's not easily discoverable. Password protection is desiable if you're working on a site that is under NDA or if maybe contains confidential information while under development.

To password protect a site go to Sites > Your Site > Manage > Authentication (button)

]]>
Tue, 26 Jan 2021 00:00:00 +0000
<![CDATA[Pulling Changes from a Statamic “Solo” Site]]> https://jaygeorge.co.uk/blog/pulling-changes-from-a-statamic-production-site-on-ploi https://jaygeorge.co.uk/blog/pulling-changes-from-a-statamic-production-site-on-ploi In this post, we'll go through how to pull down Git changes with a Statamic site. I'll specifically cover Ploi, but the steps will be similar on other platforms. This assumes that you have established an SSH connection to your server—if you haven't got this sorted, check out my earlier video, Setting Up SSH and SFTP Access With Ploi.

There are a few ways to use Statamic—workflow and licence-wise. This video may be useful if you're checking out Statamic with a solo licence and need to pull down some changes from your production environment, or you may just want to make sure your server can push to your repo via SSH if you're setting up Statamic Pro Git integration.

Make Sure You Have Your Repository Linked to Ploi Via SSH

One “Gotcha” with Ploi is if you link to a repository using the built-in “wizard” it will link to your repository using the OAuth protocol. Oath defaults to HTTPS, which means we won't be using SSH to push changes. This causes issues when trying to push back to the repository.

To solve this, when you link a site to a repository in Ploi, instead of selecting your provider, choose “Custom”. At this point, you need to ensure that you add your Ploi sever's SSH key to your account with your provider. Ploi will show you the SSH key to add when you select “Custom”. Copy the key, and (in Bitbucket, for example) go to your Personal Settings > SSH Keys > Add Key – paste in the copied SSH key and call it something like “Ploi - Name of your server”.

Go back into your repository in Bitbucket and click the “Clone” button in the top right. This will reveal the address of your Bitbucket repository. It will look something like this:

git@bitbucket.org:jaygeorge/jaygeorge.co.uk-statamic.git

Paste this into the Repository field in Ploi, select “Install composer dependencies” as usual and then click “Install Repository”. A huge thank you to Stephen Meehan for helping me out with this gotcha.

Check The Git Status On Your Server and Commit Changes to Git

  1. SSH into your machine, using a command like ssh ploi@yourserveripaddresshere

  2. Make sure you're in the correct directory—with Ploi that'll probably be a command like: cd yourdomainname.com

  3. git remote -v this should now show you two SSH-style addresses—one for fetch and one for pull.

  4. git status to see if there are any changes to the production site that you can push up to Git.

  5. Go ahead and add your changes to production e.g.

    1. git add .

    2. git commit -m "Content changes"

    3. git push

You should now be able to pull your changes down to your site locally using the git pull command.

]]>
Fri, 15 Jan 2021 00:00:00 +0000
<![CDATA[Setting up SSH and SFTP Access with Ploi]]> https://jaygeorge.co.uk/blog/setting-up-ssh-and-sftp-access-with-ploi https://jaygeorge.co.uk/blog/setting-up-ssh-and-sftp-access-with-ploi This post covers how to set up SSH and SFTP access with Ploi. While you don't need either of these things set up to deploy a site with Statamic, they can still be handy for troubleshooting and understanding what's going on.

Adding Your Computer’s SSH Key to Ploi

You'll first need to add your computer's SSH key to Ploi. You'll also need to do this if you connect via SFTP using software that uses your computer's SSH key (Forklift is an example of this).

  1. Copy your computer's SSH key. You can do this by running cat ~/.ssh/id_rsa.pub if you have a key with RSA encryption, or cat ~/.ssh/id_ed25519.pub if you have a key with ED encryption

  2. Open Terminal and SSH into your server by running ssh ploi@youripaddresshere, which will look something like ssh ploi@178.128.35.22. You should now be logged into your server.

Making Your SSH Key Persistent

If you're running macOS 10.12 or later (you probably are) then you'll need to do a few things to make your SSH key persistent. Create a config file in your SSH directory (the same directory where your public key is, e.g., .ssh/) and in the config file add the text:

Host *
 AddKeysToAgent yes
 UseKeychain yes
 IdentityFile ~/.ssh/id_ed25519

If you're running with the older RSA encryption then it will look like this:

Host *
 AddKeysToAgent yes
 UseKeychain yes
 IdentityFile ~/.ssh/id_rsa

Finally, run the following in Terminal:

ssh-add -K ~/.ssh/id_ed25519

Or if you're running with the older RSA encryption:

ssh-add -K ~/.ssh/id_rsa

SFTP Details

This is a sample of what your SFTP details will look like:

Protocol: SFTP
Server: 46.101.80.111 (replace this with your server's ip address)
Username: ploi
Password: this will be the 'sudo' password you were sent when Ploi installed your server
Port: 22
]]>
Thu, 14 Jan 2021 00:00:00 +0000
<![CDATA[Downloading and Installing an Existing Statamic Site]]> https://jaygeorge.co.uk/blog/downloading-and-installing-an-existing-statamic-site https://jaygeorge.co.uk/blog/downloading-and-installing-an-existing-statamic-site In this post, I'll walk through downloading and running an existing Statamic repository. This is a handy reference if you've got a new machine, have a fresh install of macOS, or maybe you've inherited a Statamic repository.

Once you've cloned the site into your Sites folder, it's handy to ensure that your project folder has the same name as the domain so valet can run it easily, e.g. for my site—https://jaygeorge.wip—my project folder is called jaygeorge

If you're running valet park on your Sites you should be able to boot up http://yoursitename.wip (or maybe http://yoursitename.test if you haven't changed the default TLD). You can go a step further and run your domain on HTTPS by typing valet secure yoursitename

Installing the Site with Composer

Composer needs to do its thing and install the site. Run the following commands:

  1. composer update

  2. composer install

At this point, you need to ensure you have an environment file since these are not committed to git by default, since every machine will have a slightly different environment. I find the easiest way to add an environment file is like this:

  1. Make sure you have hidden files revealed on macOS. You can do this by using the keyboard shortcut cmd + shift + . in Finder to toggle hidden files.

  2. Duplicate .env.example using cmd + d

  3. Rename the newly duplicated file as just .env

Now you can run the following commands:

php artisan key:generate
php artisan optimize
php please cache:clear
php please stache:refresh
]]>
Wed, 13 Jan 2021 00:00:00 +0000
<![CDATA[Setting up Statamic v3 on MacOS – Improving Image Quality with ImageMagick]]> https://jaygeorge.co.uk/blog/setting-up-a-statamic-developer-environment-on-macos-improving-image-quality-with-imagemagick https://jaygeorge.co.uk/blog/setting-up-a-statamic-developer-environment-on-macos-improving-image-quality-with-imagemagick As part of my Statamic series, this post covers installing ImageMagick locally to process images, to get superior image quality on your sites.

You may be wondering “Why would I want to do this?” By default, like most CMS’s, Statamic generates images using software called “GD” (Graphics Draw). For most cases, this will probably be an OK default, but from my experience using ImageMagick as alternative image processing software generates superior images—especially with larger, more noticeable images.

Installing ImageMagick Locally

Even if you're comfortable getting ImageMagick installed on your production server, installing locally will likely be a different process.

  1. Open yoursite/config/statamic/assets.php

  2. Search for driver and change the value to imagick

  3. Make sure you have homebrew installed. To check if you have homebrew installed, you can run brew -v. If Terminal tells you the version number, then you're good to go. Otherwise, download homebrew from https://brew.sh/

  4. Run brew install imagemagick. Check for any errors. At this point in the video, I was prompted to run a command to remove some leftover files.

  5. Run brew install pkg-config

  6. When prompted with Please provide the prefix of Imagemagick installation [autodetect] : just hit enter.

  7. Once complete try running valet restart and refreshing your site. You'll know ImageMagick is successfully installed if 1) it generates Statamic Glide images correctly, and 2) if you go to yoursite/cp/utilities/phpinfo you should a new full section with the headline imagick, with the first row of the section detailing the imagick module version

Fixing Errors

In my experience development environment things seldom “just work”—there's either something you forgot to set or some error you need to deal with. While ImageMagick usually runs smoothly you'll see in the video I ran into an error. The good news is you can usually Google search-engine your way out of an error when it comes to popular software—and luckily ImageMagick is relatively popular.

Before you start searching for fixes it may be worth clearing the cache first with:

php please glide:clear

This didn't help the error I ran into—which in this case was:

warning: mkdir(): File exists in System.php on line 294

I eventually found an article by Patrique Ouimet, which detailed a fix—thank you, Patrique! https://patriqueouimet.ca/tip/installing-php-and-pecl-extensions-on-macos

In this case, you needed to run:

pecl config-get ext_dir | pbcopy

then type:

mkdir -p

followed by pressing cmd + v to paste the value you just copied to your clipboard.

Once this command has been run, and the directory has been created, try running pecl install imagick again and maybe run php please glide:clear to be on the safe side. Finally valet restart and go back to your Utilities > PHP Info in your control panel. If everything's worked out, you should now see an Imagick section here.

]]>
Tue, 12 Jan 2021 00:00:00 +0000
<![CDATA[Setting up Statamic v3 on MacOS Part 4 of 4 (Aside) Working with Git]]> https://jaygeorge.co.uk/blog/setting-up-a-statamic-developer-environment-on-macos-part-4-aside-working-with-git https://jaygeorge.co.uk/blog/setting-up-a-statamic-developer-environment-on-macos-part-4-aside-working-with-git In this post, I'll cover how to get your project into Git and get your machine to talk with a Git repository-hosting service such as Bitbucket. Using Git means we can save our project in different states, roll changes back if we make a mistake and also it allows us to push up/pull down changes to the website and its content.

Authorising Your Computer with SSH in Bitbucket

FYI if you've decided to store your files in a Github repository instead, this process will be very similar.

  1. Go ahead and set up a Bitbucket account if you don't already have one.

  2. When you log in to Bitbucket, you should be in the “Repositories” dashboard. From here look in the left-hand corner where you should see your avatar. Click this and then “Personal Settings” then “SSH Keys”.

  3. We now need to generate an SSH key on our machine. Open the Terminal application and paste in ssh-keygen -t ed25519 -C "your_email@example.com", substituting the email address for whatever your Bitbucket email address is.

  4. Once a key pair has been generated, you'll be prompted to enter a file to save the key. Press enter to accept the default location.

  5. You'll now be prompted to generate a passphrase. This is basically a password. Please make a note of whatever you type in because you'll need it later. Terminal should now inform you that a fingerprint has been generated.

  6. Back in Bitbucket press the add key button

  7. Give the key a label; for example, the name of the machine you've used to generate the key. In my case, I called it MacBook 2018

  8. At the time of writing Bitbucket prompts you to copy the key from your machine using a command that references an older encryption method (RSA). Since we've generated a key using a newer encryption standard, an RSA copy command won't work. To be sure you get the key, you can copy it directly from the file. Go to your home directory and make sure hidden files are showing in Finder—you can toggle these on/off using the keyboard shortcut cmd + shift + .

  9. You should see a .ssh directory. Inside the folder look for id_ed25519.pub. Open this in a text editor and copy the contents of this file. Paste this into the key field in Bitbucket, then press Add key.

Create a New Repository in BitBucket

In the repository dashboard in Bitbucket create a new repository. You can call the Repository whatever you like, but usually, you'll call it the name of your site. I find it useful to specify the site's technology, for example for my own site I've called it “jaygeorge-statamic”. This means if I ever switch to a different CMS in future (which I have done in the past!) I can store that as a separate repository, e.g. “jaygeorge-perch”.

I find it easier to select “no” when it asks me if I'd like to create other files—I prefer to create the repo locally and manually add these things. This is just personal preference though—you may find it easier to let Bitbucket do this for you.

Creating a Project in Git

It's now possible to clone down the repository using the Sourcetree app. This may be the simplest way to do things, but here I'll cover creating the repository locally from scratch and linking it to Bitbucket.

  1. If you don't already have a project in your Sites folder go ahead and make one, e.g. create a subfolder in Sites called test

  2. We now need to make sure we're in that project folder in Terminal. In Finder press cmd + c on the project folder to “copy” it. Back in Terminal type cd (with a space afterwards) and then press cmd + v to paste the directory path we've just copied. Hit enter

  3. The Terminal window's top bar should now show the name of the project folder we're in.

  4. Now we're going to create a Git project. To do this run git init and hit enter. Now run git add . – this command will add all your files to the repository. Now run git commit -m "Initial commit" – this command “commits” the files you've just added. The -m stands for “message”.

Adding Bitbucket as a Remote Repository

We've got our repository set up locally, and now we want to synchronise it with a host (in our case Bitbucket). Eventually, we will set up our production server to “pull” our code from Bitbucket—but that's for another day!

  1. Once you've created a repository back on the Bitbucket site, it should give you a few different sample commands. We can skip a few of these since we've already created a git repository, added files, and committed. We need to add the Bitbucket repository we've created as a “remote” now. You should see the command we need to run on the Bitbucket site, in my example it was git remote add origin git@bitbucket.org:jaygeorge/test.git.

  2. push up your commits to the master branch with git push -u origin master. If Terminal tells you the authenticity of the host can't be established say yes to continue. At this point, you'll be prompted to enter your passphrase that we made up earlier. Do so and hit enter (it'll be invisible so don't worry if you don't see anything while you're typing)

Once you've “pushed up” the code, at this point if you go back to Bitbucket and refresh the page you should see your commit along with its message. PS If you try to push to the repository again and get a permission denied public key message, try restarting your computer and trying again.

]]>
Mon, 11 Jan 2021 00:00:00 +0000
<![CDATA[Setting up Statamic v3 on MacOS Part 4 of 4 – Publishing a Statamic Site]]> https://jaygeorge.co.uk/blog/setting-up-statamic-v3-on-macos-part-4-of-4-publishing-a-statamic-site https://jaygeorge.co.uk/blog/setting-up-statamic-v3-on-macos-part-4-of-4-publishing-a-statamic-site In this post, part 4, we'll cover deploying a Statamic site. The one thing to bear in mind when you're thinking about which host to use is that Statamic runs on Laravel. There are definitely a few differences with hosting a Laravel site, most notably…

  1. You typically need to run a set of commands after each deploy. These commands may do things like clear the cache, and recompile assets like Tailwind / minified CSS and JS using Webpack.

  2. Laravel needs to be run on a folder named public rather than the wide-standard for hosts, public_html. This can be a change to resolve, especially on shared hosting where it's typically not even possible to rename the public_html folder.

Using a host that supports Laravel environments makes things a lot easier and I strongly recommend you go this route unless you love tinkering with servers and making your life more difficult.

Choosing a Host

N.B. If you decide to sign up to Ploi I would very much appreciate it if you used my referral code https://ploi.io/register?referrer=JjynFt5S8WmoZbiAZO3E

The two most popular “server management” solutions (note: not quite the same as a host—we’ll get to that later)—are:

  • Laravel Forge – built by Taylor Otwell. Taylor is the creator of the Laravel Framework and so this is a solid choice.

  • Ploi – Similar to Forge but more encompassing, with extra bells and whistles which make it easier to connect to repositories, and with a much nicer UI, in my opinion. Ploi also has PHPMyAdmin built-in, so if you have existing sites on other CMS's like WordPress or Perch (which I did), you can migrate them and keep everything in one place.

Whether you choose Forge or Laravel, both of these services have the same purpose – to administrate a host/server more easily. In terms of hosts, the most popular options for Statamic are Digital Ocean and Linode. Digital Ocean seems to be the favourite, and so my final recommendation would be a Statamic setup of using Ploi to manage a Digital Ocean server.

Publishing a Statamic Site using Ploi

Let's start from scratch with a free Ploi trial—we'll go from signing up to a trial to getting a Statamic site live. p.s. if you decide you like Ploi and want to help a man out, please use my referral code: https://ploi.io/register?referrer=JjynFt5S8WmoZbiAZO3E

  1. Sign up to a free trial on ploi.io

  2. Add a Git Provider – In the Dashboard click the “Link Git Provider” button, where you'll be prompted to link to your GitHub, BitBucket, or GitLab accounts. If you're a little unsure on Git, my Working With Git video may help you.

  3. Link to a Server Provider – Select your Server Provider. In my case, I'm using Digital Ocean.

    1. In Digital Ocean go to “API” in the bottom of the left column.

    2. Select “Generate a new Token”, call it something like “Ploi”.

    3. Copy the token using the little “copy” link.

    4. Go back to Ploi and paste the token in the “API Key” field. Label it something like “Digital Ocean” and click “Add Provider”.

  4. Create a Server – In the Dashboard click the “Create Server” button. Select your server provider and then in the “Details” section use the Credentials dropdown to select the account you just created. Fill the in the details here. If you're just starting out the lowest server plan should be fine. You'll want to make sure you select a Server Region that's closest to your main customer base. When you're done click the “Create Server” button. Ploi will now use Digital Ocean's API to create a server for you on their platform. This might take a bit of time – go and get a cuppa tea—you deserve it! it took 20 minutes for the progress bar to reach 100% for me.

At this point you'll be e-mailed server details. Save these somewhere safe (you'll need them!). I would personally then delete the e-mail for security reasons.

Recommended Ploi Settings

  • Click your avatar in the top right > Profile – set up TwoFactor Authentication here.

  • Settings > Theme mode – change this to Dark mode if you're a fan.

  • I'd recommend you use ImageMagick to process images rather than GD, which produces better quality image processing. For more information on that see my post about getting ImageMagick working locally. To enable ImageMagick in Ploi, go to Servers > PHP > Manage Extensions and check Imagick

Creating a Site

  1. In the Ploi dashboard > left hand menu > Servers > select your server – add a domain you'd like to link here e.g. yourdomain.com and click Add Site.

  2. Once the site has been created, click it, and select “Git Install Repository”, choose your provider and select your repository. Make sure you select “Install composer dependencies”, and then click Install Repository.

  3. At this point you'll be prompted to add some recommended script commands, ignore this – I'll give you some recommendations instead. Click “Ignore suggestions”

Once you can see the Deploy script, add these lines below where it says “echo "🚀 Application deployed!"”

npm install
npm run production

php artisan optimize
php please cache:clear
php please stache:refresh

php artisan route:cache
php artisan view:clear

The full deploy script should now look something like this (bear in mind your site directory will be different and your php version might be different).

cd /home/ploi/yourdomain.com
git pull origin master
composer install --no-interaction --prefer-dist --optimize-autoloader
echo "" | sudo -S service php7.4-fpm reload

echo "🚀 Application deployed!"

npm install
npm run production

php artisan optimize
php please cache:clear
php please stache:refresh

php artisan route:cache
php artisan view:clear

When you've finished editing the deploy script click “Save”

Click the “Edit Environment” button in the top right:

  • Change the APP_URL to https://yourdomain.com (rather than plain ol’ http).

  • Change the APP_ENV to production

Then in the top right click “Deploy Now”. Once you've successfully deployed your repository you can remove the npm install line.

Pointing your DNS to Ploi

In your domain registrar's DNS records, you should have the following three lines:

  1. An A record for * with a value of your server’s IP address (which you can find in the top left of Ploi once you're in a server or its sites)

  2. An A record for @ with a value of your server’s IP address

  3. A cname record for www with a value of yourdomain.com

Setting up an SSL Certificate for your Domain with Ploi

Once you've gone into your site in Ploi > left hand menu > SSL – accept the defaults here and click “Add certificate”. At this point Ploi will check with the DNS to connect. if you've correctly pointed your DNS to ploi this should work.

Automatically Deploying

When you push to your installed branch, Ploi will run the deploy script for you.

A final thing to consider is whether you'd like to automatically deploy your site when you push up to Git. You may want to be careful with this if you're handling a big client but otherwise, this is a big productivity boost. Once you've gone into your site in Ploi > left hand menu > Repository – scroll down to the Quick deploy heading and click “Enable Quick Deploy”. Another possible workflow is if you set up a staging site on Ploi and automatically deploy to that.

Quick Deploy Not Showing

I've run into a problem previously where "Quick Deploy" wasn't visible in the "Repository" section. I believe this happens when you initially add the repository using the "Custom" option rather than the built-in BitBucket/GitHub integration.

It's still possible to enable quick deploy though. To get around this, in Ploi > left hand menu > Repository – scroll down to the Repository section, and change "Custom" to "BitBucket" or "GitHub". Make sure the repository name is in the format "username/repo_name", for example "jaygeorge/london-local". The repository URL field should already automatically be in the correct format from when it was previously saved as "Custom", e.g. "git@bitbucket.org/jaygeorge/london-local.git"

Once you've turned Quick Deploy on, if you like you can switch back to "Custom" and Ploi should continue to quick-deploy.

]]>
Sun, 10 Jan 2021 00:00:00 +0000
<![CDATA[Setting up Statamic v3 on MacOS Part 3 of 4 – Installing Statamic]]> https://jaygeorge.co.uk/blog/setting-up-a-statamic-developer-environment-on-macos-part-3-installing-statamic-with-a-starter-kit https://jaygeorge.co.uk/blog/setting-up-a-statamic-developer-environment-on-macos-part-3-installing-statamic-with-a-starter-kit N.B. In the video introduction, I refer to this video as “Part 2”, which is incorrect—this is actually part 3. In part 1, we went through setting up Composer, which is used to manage dependencies, and also Valet, which is used to set up a hosting environment. In part 2, we covered using valet to generate domains automatically.

In this post, part 3, we'll cover installing Statamic and setting up a site. The best way to do this is to install a couple of starter kits. I recommend you first install a plain ol’ Statamic installation so you can start building things from scratch and then secondly install a starter “kit”, which is a pre-made website which we can copy and learn from.

To start, go to the Installation page in the docs: https://statamic.dev/installation. There are two different ways to install Statamic using Composer. The recommended way is to install the Statamic CLI (Command Line Interface)—this adds a “helper” layer on top of Composer, so it's the preferred way to go. Run the command:

composer global require statamic/cli

After this dependency is installed, try running:

statamic new somesitename

If You Get the Error: command not found: statamic

This is an issue with your $PATH not having the global .composer/vendor/bin directory in it (source). Try the following:

  1. Run sudo nano /etc/paths

  2. Use your down arrow key to go to the bottom of the list and add a new line called /Users/your-username-here/.composer/vendor/bin

  3. Exit nano by pressing ctrl + x and say yes to save

  4. Close the Terminal window and open a new one

  5. Try the command again: statamic new somesitename

Use the Wizard to Install A Starter Site and Starter Kit

Once you've got the interactive wizard going, first make sure you're in your Sites directory in Terminal, then run statamic new starter. When the wizard asks you “Which Starter kit would you like to install from?” type 0 to select the first option and install a Statamic starter site.

When the script runs don't worry about any “package abandoned” yellow warnings—this is more of a soft concern for the Statamic developer team to address in future Statamic releases.

Rerun the wizard; `statamic new kit`. When the wizard asks you “Which Starter kit would you like to install from?” choose a kit, e.g. type 3.

Make Sure You Have Your Domains Set Up

At this point, if you're using valet park to “park” your Sites directory, you should be able to go to the relevant domain e.g. http://starter.wip or the default TLD of http://starter.test

I'd still recommend you secure the site by typing the command valet secure yoursitename. It takes 2 seconds and a) gets rid of the ugly red padlock, and b) bear in mind your live site will be HTTPS, so it gets us one step closer to your production environment with minimum effort.

Once you've secured your domains you should be able to go to:

  • https://starter.wip

  • https://nameofyourkit.wip

Create A User to Gain Access to the Control Panel

You'll first need to create a user to access the control panel. You can do this by:

  • First, make sure you are in your starter site directory, e.g. run the command cd /Users/yourhomedirectoryhere/Sites/starter

  • Run php please make:user (documentation)

  • Go through the wizard questions

Now you should be able to go to the control panel e.g. https://starter.wip/cp. You can now repeat the process for your second site…

  • First, make sure you are in your starter kit site directory, e.g. run the command cd /Users/yourhomedirectoryhere/Sites/nameofyourkit

  • Run php please make:user

  • Go through the wizard questions

]]>
Sat, 09 Jan 2021 00:00:00 +0000