This tutorial walks you through all the steps needed to set up your own Koriander CMS blog on AWS S3 and CloudFront.

Here's what you're going to learn in this tutorial:

1. How to install Koriander CMS and make your first page.
2. What AWS resources you need to upload your Koriander site.
3. How to configure Koriander to upload your site.

Install Koriander CMS

Install Koriander CMS on your computer using pipx. Install pipx using the official pipx installation instructions. Open a terminal on your computer and make sure that you can run pipx by typing the following command and pressing the Enter key:

pipx --version

On the author's computer this command prints the following:

1.8.0

If you see pipx printing a version number like 1.8.0, you're ready to install Koriander CMS on your computer. Type the following command and press the Enter key:

pipx install koriander

When pipx finishes installing Koriander CMS, pipx install koriander prints the following:

  installed package koriander 0.18.0, installed using Python 3.13.13
  These apps are now globally available
    - koriander
done! ✨ 🌟 ✨

The version numbers Koriander CMS 0.18.0 and Python 3.13.13 may be different when you install Koriander CMS.

Launch Koriander CMS

Type the following command in your terminal to launch Koriander CMS:

koriander

When you launch Koriander CMS, your browser should automatically open the index page. If your browser doesn't open the index page, copy the green address below the Log in with the following link: line and paste it into your browser address bar:

The next picture shows the Koriander CMS index page at /index.html. Press the Edit link in the top toolbar to edit the page contents.

You've opened the page editor for the index page. In Koriander, pages use Markdown for formatting. Here's the default index page content when you've just installed Koriander:

Add your own page content on the left side of the Markdown editor:

Save your changes by pressing the Save button in the right menu under Publish:

Go back to the start page by pressing the View on site link in the right menu under Publish.

This screenshot shows how the index page looks like after changing it:

Set up AWS resources

S3 Bucket

Create an S3 bucket in your preferred AWS zone. Visit the Creating a general purpose bucket tutorial and refer to the Using the S3 console section if you're using the S3 console.

Here you can see the screens that the author walked through to create a test bucket called “koriander-bucket” for this tutorial. First, go to the S3 buckets page in the AWS console:

On the Buckets overview page, press the orange Create bucket button:

Enter a name for your bucket in the following Create bucket screen:

Review the other settings and finish creating your bucket by pressing the Create bucket button:

CloudFront Distribution

Now that you've created your S3 bucket you need a CloudFront distribution to make the S3 bucket contents publicly available. Go to CloudFront in the AWS console and press the orange Create distribution button:

Give your CloudFront distribution a name and press Next. In this example, the distribution name is “koriander-cloudfront”:

On the next Specify origin screen, make sure that you select Amazon S3 as Origin type and press the blue Browse S3 button:

Select your bucket in the S3 Origin popup and confirm with Choose:

Decide whether you need a Web Application Firewall (WAF) and confirm your decision by pressing the Next button:

Finish creating your CloudFront distribution by pressing Create distribution on the next screen:

After you press Create distribution, the AWS console should show you your new CloudFront distribution and its Distribution domain name. This is where you can access your Koriander site once you've finished uploading it to your S3 bucket.

Finally, you'll set up a root object for your CloudFront distribution. Press the Edit button next to Settings. Enter “index.html” under Default root object - optional. Scroll down and press Save changes.

Configure an IAM user for your S3 bucket

Go to IAM and create a user for your newly created S3 bucket. Review the Create an IAM user in your AWS account tutorial on docs.aws.amazon.com if you're not sure how to continue.

Press the orange Create user button:

Enter the IAM user name. In this example, the user name is “koriander-bucket-user”. Press Next to continue to the Set permissions screen.

On the Set permissions screen, select Attach policies directly under Permissions options and press the blue Create policy button:

This opens a new window. In the Policy editor, enter the following policy ³ while adjusting the “koriander-bucket” name for the bucket name that you've chosen:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "ListObjectsInBucket",
            "Effect": "Allow",
            "Action": ["s3:ListBucket"],
            "Resource": ["arn:aws:s3:::koriander-bucket"]
        },
        {
            "Sid": "AllObjectActions",
            "Effect": "Allow",
            "Action": ["s3:*Object"],
            "Resource": ["arn:aws:s3:::koriander-bucket/*"]
        }
    ]
}

Here's what it should look like when you enter your user policy. Press Next to continue creating your IAM policy:

On the next Review and create screen, enter a name for the policy and press Create policy.

On the next screen you should see the follow green confirmation:

Policy koriander-bucket-policy created

Close this Policies window and go back to the IAM user creation screen. Press the refresh button in the policy selector. Attach the “koriander-bucket-policy” to the IAM user by selecting it in the following list and pressing Next.

Finish creating your user by pressing the orange Create user button:

You should now see your new “koriander-bucket-user” in the list of IAM users:

Open the “koriander-bucket-user” and select the Security credentials tab and press Create access key.

Select Other¹ as your use case on the next screen and press Next:

Enter a description for your access key and press Create access key:

On the next screen, press Download .csv file to download your access key.

Go to the user's page and select the Security credentials tab again. Confirm that your access key is there:

The .csv file should contain the data for the access key that you've just created:

You're going to use the Access key ID and Secret access key in the next step.

Configure S3 uploads in your Koriander CMS site

Open the Koriander administration screen by following the Admin link in the toolbar:

In the administration screen, select Site settings in the Koriander CMS table.

Select the grey S3 upload link next to the Change Site settings title.

On the next screen, select AWS S3 under S3 endpoint type and press Continue:

Select your AWS S3 region. The bucket in this tutorial lives in the “ap-southeast-2”² AWS S3 region. Press the Continue button.

On the next screen, enter your S3 bucket, S3 access key ID and S3 access key. Under S3 bucket, enter the name of the bucket that you've just created. For S3 access key ID and S3 secret access key, enter the two values from the .csv file that you've downloaded. Press Continue to confirm:

You're ready to upload your site to S3 and publish it with CloudFront.

Upload to S3

Pressing Continue should take you to the Upload to S3 screen. Select Dry run and press Upload.

When Koriander performs a Dry run, it checks which files in your site have changed or which ones you've added or removed. You can always try a Dry run if you're not sure what changes.

Koriander CMS now tells you which files it would upload to your S3 bucket, but hasn't yet uploaded since it's a Dry run:

Press Upload now to upload your Koriander CMS site to your AWS S3 bucket. This takes you to a results page:

Confirm that you've uploaded your file to your bucket by opening the bucket in the AWS Console:

Go to your CloudFront distribution. You should see the Last modified field updating. Note the “…cloudfront.net” Distribution domain name:

Now open the “…cloudfront.net” Distribution domain name in your browser. You should see your own Koriander CMS site appear:

You have just published your Koriander Site using AWS S3 and CloudFront.

Here are some more things that you can do:

• Create more pages in Koriander CMS
• Add pictures to your Koriander CMS pages
• Customize your Koriander CMS page templates and styles
• Use your own domain name with CloudFront: Use custom URLs by adding alternate domain names (CNAMEs)