📅 2026/01/12 ⏱️ 16 min read

Deploy Guide

Guide |

#deploy #cloudflare #guide #setup

Deploy Guide

This guide explains how to deploy your itzpapa blog to Cloudflare Workers. We’ll walk through every step from getting the project to publishing it live.

Introduction

itzpapa is an Astro blog solution for Obsidian users. Using Cloudflare Workers, you can host your static site for free with excellent performance.

Target Audience

• Users who want to start a blog using the itzpapa template
• Users who want to learn how to deploy to Cloudflare Workers
• Users interested in both GitHub-connected and direct upload methods

What This Guide Covers

1. Getting and setting up the project
2. Required configuration before deployment
3. Building the project
4. Deploying to Cloudflare Workers
5. Comparing deployment methods
6. External image hosting (optional)

1. Getting and Setting Up the Project

Cloning the Repository

Clone the project from GitHub:

git clone https://github.com/hachian/itzpapa.git
cd itzpapa

If you want to manage it as your own repository, we recommend forking it on GitHub first, then cloning your fork.

Installing Dependencies

Install dependencies using your package manager.

Linux / macOS:

npm install

Windows:

On Windows, we recommend using pnpm. The sharp package may cause dependency resolution errors with npm.

npm install -g pnpm
pnpm install

Starting the Development Server

After installing dependencies, start the development server to verify everything works:

npm run dev

Open your browser and navigate to the following URL to confirm the site displays correctly:

Local Preview URL: http://localhost:4321

The first startup may take a few seconds as it generates logo images.

2. Required Configuration Before Deployment

Before deploying, you must change the following settings. Without these changes, the original itzpapa site information will be published.

Configuring site.config.ts

Edit site.config.ts in the project root.

Required Changes

site: {
  title: 'My Blog',  // <- Required change
  description: 'A blog about programming and technology',  // <- Required change
  author: 'Your Name',  // <- Required change
  baseUrl: 'https://yourdomain.com',  // <- Required change
  language: 'en',
},

Comment System (giscus) Configuration

In the features.comments section, either disable comments or configure it for your own repository.

To disable comments:

features: {
  comments: {
    enabled: false,
  },
},

To configure for your repository:

Visit giscus.app to generate configuration values for your repository:

features: {
  comments: {
    enabled: true,
    provider: 'giscus',
    config: {
      repo: 'yourusername/your-repo',  // <- Your repository
      repoId: 'R_xxxxx',  // <- Generated by giscus.app
      category: 'Comments',
      categoryId: 'DIC_xxxxx',  // <- Generated by giscus.app
    },
  },
},

If you don’t change the comment settings, comments will be posted to the original itzpapa repository.

Configuring astro.config.mjs

Update the site property in astro.config.mjs to match the baseUrl in site.config.ts:

export default defineConfig({
  site: 'https://yourdomain.com',  // <- Same value as site.baseUrl
  // ...
});

This value is used for sitemap generation and canonical URLs.

3. Building

Build Commands

itzpapa has two build commands:

For local builds:

npm run build

For CI/CD builds (Cloudflare Workers, etc.):

npm run build:ci

npm run build loads the .env file during build. This is needed when using the external image hosting feature. In CI environments, set environment variables separately and use npm run build:ci.

Output Directory and Preview

The build output is in the ./dist/ directory.

# Preview the build result
npm run preview

The preview server starts at http://localhost:4321 where you can verify the build output.

Environment Variables

Environment variables are managed in the .env file. Create a .env file in the project root:

# Example .env
IMAGE_HOSTING_ENABLED=false
# Additional settings needed for external image hosting (see below)

Don’t commit the .env file to Git as it may contain sensitive information.

4. Deploying to Cloudflare Workers

There are two ways to deploy to Cloudflare Workers.

Wrangler Configuration

itzpapa includes a wrangler.jsonc file for Cloudflare Workers deployment:

{
  "name": "itzpapa",
  "compatibility_date": "2026-01-18",
  "assets": {
    "directory": "./dist"
  }
}

Update the name field to your project name (lowercase letters, numbers, and hyphens only).

Method 1: GitHub Integration (Recommended)

Connect your GitHub repository for automatic deployment on push.

Steps:

1. Log in to Cloudflare Dashboard
2. Navigate to “Workers & Pages” -> “Create” -> “Create Worker”
3. Select “Import a repository”
4. Connect your GitHub account and select the target repository
5. Enter build settings

Build Settings:

Environment Variables (if needed):

6. Click “Save and Deploy”

Once deployed, your site will be accessible at a URL like https://your-project.workers.dev.

To set up a custom domain, go to “Settings” -> “Domains & Routes” in your Worker settings.

Method 2: Direct Upload (CLI)

Upload directly from your local machine using CLI without GitHub.

Steps:

1. Install Wrangler

npm install -g wrangler

2. Log in to Cloudflare

wrangler login

3. Build the project

npm run build

4. Deploy to Cloudflare Workers

npx wrangler deploy

The wrangler.jsonc configuration file handles the deployment settings. On first run, the worker is created automatically.

The project name in wrangler.jsonc can only contain lowercase letters, numbers, and hyphens.

About Security Headers

itzpapa includes a public/_headers file that sets security headers:

/*
  X-Content-Type-Options: nosniff
  X-Frame-Options: DENY
  Referrer-Policy: strict-origin-when-cross-origin

These headers are automatically applied on Cloudflare Workers. Customize them as needed.

5. Comparing Deployment Methods

GitHub Integration Benefits:

• Automatic deployment on push
• Preview environment created for each pull request
• Rollback to any commit from history
• Ideal for team development

Direct Upload Benefits:

• No GitHub account required
• Simple setup
• Deploy local changes immediately
• Useful as a private test environment

For ongoing blog maintenance, we recommend GitHub integration.

6. External Image Hosting (Optional)

For blogs with many images, hosting images on S3 or Cloudflare R2 reduces deployment size and enables fast CDN delivery.

Environment Variable Configuration

Add the following environment variables to your .env file:

# Enable external image hosting
IMAGE_HOSTING_ENABLED=true
IMAGE_HOSTING_PROVIDER=R2  # or S3
IMAGE_HOSTING_BUCKET=your-bucket-name
IMAGE_HOST_URL=https://images.yourdomain.com

Cloudflare R2 Example

# .env - Cloudflare R2
IMAGE_HOSTING_ENABLED=true
IMAGE_HOSTING_PROVIDER=R2
IMAGE_HOSTING_BUCKET=my-blog-images
IMAGE_HOST_URL=https://images.example.com

# R2 Credentials
R2_ACCESS_KEY_ID=your_access_key_id
R2_SECRET_ACCESS_KEY=your_secret_access_key
R2_ACCOUNT_ID=your_cloudflare_account_id

R2 Setup Steps:

1. In Cloudflare Dashboard, go to “R2” -> “Create bucket”
2. Create an API token under “Manage R2 API Tokens”
3. Configure a custom domain (optional but recommended)

AWS S3 Example

# .env - AWS S3
IMAGE_HOSTING_ENABLED=true
IMAGE_HOSTING_PROVIDER=S3
IMAGE_HOSTING_BUCKET=my-blog-images
IMAGE_HOST_URL=https://my-blog-images.s3.amazonaws.com

# S3 Credentials
AWS_ACCESS_KEY_ID=your_access_key_id
AWS_SECRET_ACCESS_KEY=your_secret_access_key
AWS_REGION=ap-northeast-1

When using external image hosting, images are uploaded to S3/R2 during build and HTML image URLs are rewritten to external URLs. See the “Image External Hosting” section in Site Configuration Guide for details.

Summary

This guide covered how to deploy your itzpapa blog.

Deployment Flow:

1. Clone the repository and install dependencies
2. Edit site.config.ts and astro.config.mjs
3. Build with npm run build
4. Deploy to Cloudflare Workers

Next Steps:

• Site Configuration Guide - Review configuration details
• Markdown Syntax Guide - Learn Markdown formatting
• Obsidian Syntax Guide - Learn Obsidian syntax usage

If you have any questions, feel free to open an issue on GitHub Issues.