Step 1: Getting Started Locally

Install Astrolock and create your first site - no external setup required

Tip

You can complete this entire guide on your own - no server setup, no deployment accounts needed. Get a fully functional local site running in 15 minutes.

What You’ll Accomplish

By the end of this guide, you’ll have:

✅ Astrolock installed on your machine
✅ A working site running at http://localhost:4321
✅ Your first blog post published
✅ Understanding of how to add and preview content

Time Required: 15-20 minutes Prerequisites: A Mac or Linux computer (Windows via WSL)

Prerequisites

You need these tools installed first:

Run these commands to check:

node --version   # Need v18 or higher
yarn --version   # Need v1.22 or higher
yq --version     # Need v4 or higher

If any command fails, continue with the installation steps below.

1. Install Node.js

macOS (Homebrew)
macOS (Official)
Linux

brew install node@20

# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Fedora/RHEL
curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash -
sudo dnf install -y nodejs

2. Install Yarn

npm install -g yarn

3. Install yq

macOS
Linux

brew install yq

Note

yq is a YAML processor that Astrolock uses for configuration management.

Install Astrolock

Download and install the Astrolock CLI:

curl -sSL https://astrolock.eyelock.net/install.sh | bash

Verify the installation:

astrolock --version

You should see a version number like astrolock 0.1.0.

Create Your First Site

Initialize a New Site

Create a directory for your site and initialize it:

mkdir my-site
cd my-site
astrolock init

The wizard will ask you a few questions:

Site title [My Site]: My Amazing Blog
Site description [A modern static site]: A blog about my adventures

Configuration ready
Creating Site Files...
✓ Directories created
✓ Site images copied
✓ Configuration files created
✓ Content created

Setup Complete!

Just accept the defaults for now - you can change everything later.

Start the Development Server

Start the live development server:

astrolock write

Info

The write command:

Builds your site
Starts a local web server at http://localhost:4321
Watches for changes and auto-reloads your browser
Keeps running until you press Ctrl+C

Open http://localhost:4321 in your browser. You’ll see your new site! Keep this terminal window running.

Understanding Your Site Structure

Your site has this structure:

my-site/
├── .astrolock/
│   └── astrolock.yaml         # All configuration
├── content/
│   ├── blog/                  # Blog posts
│   ├── pages/                 # Static pages (About, Contact)
│   └── authors/               # Author profiles
└── public/
    └── images/                # Images and media files

.astrolock/astrolock.yaml - Your entire site configuration in one file:

Site metadata (title, description, URL)
Navigation menus
Collections setup
Deployment targets
Theme settings

content/ - All your written content:

blog/ - Blog posts (markdown files)
pages/ - Static pages like About, Contact
authors/ - Author profile pages

public/ - Static assets that get copied as-is:

Images, audio files, videos
Favicons, robots.txt, etc.

Create Your First Blog Post

Open a new terminal window (keep astrolock write running in the first one) and run:

astrolock content blog "My First Post"

This creates content/blog/my-first-post.md. Open it in your editor:

---
title: "My First Post"
date: 2025-12-03T01:00:00Z
author: "yourname"
categories: ["others"]
tags: ["others"]
draft: false
---

Write your content here!

Tip

The section between --- is called frontmatter. It contains metadata about your post. Everything after is your content.

Edit Your Post

Replace the content with something meaningful:

---
title: "My First Post"
date: 2025-12-03T01:00:00Z
author: "yourname"
categories: ["personal"]
tags: ["introduction", "first-post"]
draft: false
---

# Welcome to My Blog!

This is my first post on my new Astrolock site. I'm excited to start sharing my thoughts here.

## What I'll Write About

I plan to write about:
- My hobbies and interests
- Things I'm learning
- Projects I'm working on

Stay tuned for more posts!

Save the file and switch to your browser - it automatically refreshed! Your new post is now visible.

Customize Your Site

Let’s make a few quick changes to personalize your site.

Change the Site Title

Open .astrolock/astrolock.yaml and find:

site:
  title: "My Site"
  description: "A modern static site"

Change it to:

site:
  title: "My Amazing Blog"
  description: "A blog about my adventures"

Save the file - your browser will reload with the new title in the header.

Update the About Page

Open content/pages/about.md and customize it with your information:

---
title: "About Me"
description: "Learn more about me and this blog"
---

# About Me

Hi! I'm [Your Name], and this is my blog where I share my thoughts on...

## What You'll Find Here

I write about topics including:
- Topic 1
- Topic 2
- Topic 3

Feel free to reach out via my [contact page](/contact)!

Next Steps

Tip

You now have a working Astrolock site! It’s running locally and you can create content. This is everything you need to start building your site.

Continue Learning

Step 2: Advanced Features → Learn about:

Creating collections (audio, images, video)
Customizing page layouts and styles
Adding stock images
Importing existing content

CLI Reference → Quick reference for all astrolock commands

Frontmatter Reference → All available fields for blog posts and pages

Common Tasks

Stop the development server? Press Ctrl+C in the terminal running astrolock write

Create another blog post?

astrolock content blog "Post Title"

View my site? Go to http://localhost:4321 while astrolock write is running

Edit existing content? Open the markdown files in content/ with any text editor

Change the theme/colors? Edit .astrolock/astrolock.yaml - see Theme Configuration

Troubleshooting

Another application is using port 4321. Either:

Stop the other application
Kill the process: lsof -ti:4321 | xargs kill -9
Change the port in astro.config.mjs (advanced)

Make sure astrolock write is still running
Check the terminal for errors
Hard refresh your browser: Cmd+Shift+R (Mac) or Ctrl+Shift+R (Windows/Linux)
Restart the development server

The installation didn’t add Astrolock to your PATH. Add this to your ~/.bashrc or ~/.zshrc:

export PATH="$HOME/.astrolock/bin:$PATH"

Then restart your terminal or run source ~/.bashrc (or ~/.zshrc).

Warning

Still stuck? See the full troubleshooting guide or get help.