Type something to search...
to navigateto selectESC to close

Installation

Get Astrolock installed and ready to use

Installation

Time: 10-15 minutes | Difficulty: Beginner

Get Astrolock installed and verify everything is working.

Prerequisites

Before installing Astrolock, you need:

  • Node.js v18 or higher
  • Yarn package manager
  • Terminal access (Terminal.app on macOS, or any terminal on Linux/Windows)
  • Git (optional, but recommended)

Step 1: Install Node.js and Yarn

macOS

Using Homebrew (recommended):

# Install Homebrew if you don't have it
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Node.js and Yarn
brew install node@18 yarn

# Verify installation
node --version   # Should show v18.x.x or higher
yarn --version   # Should show 1.22.x or higher

Linux

Using nvm (Node Version Manager):

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Restart your terminal or run:
source ~/.bashrc

# Install Node.js 18
nvm install 18
nvm use 18

# Install Yarn
npm install -g yarn

# Verify installation
node --version   # Should show v18.x.x
yarn --version   # Should show 1.22.x

Windows

Using Windows Subsystem for Linux (WSL) - Recommended:

  1. Install WSL2 following Microsoft’s guide
  2. Follow the Linux instructions above within your WSL terminal

Alternative - Native Windows:

  1. Download Node.js 18 from nodejs.org
  2. Run the installer
  3. Open PowerShell and run: 
    npm install -g yarn

Step 2: Install Astrolock

Clone the Astrolock repository and install dependencies:

# Clone the repository
git clone https://github.com/eyelock/astrolock.git

# Navigate to the directory
cd astrolock

# Install dependencies
yarn install

What this does:

  • Downloads the Astrolock code
  • Installs all required packages
  • Prepares the CLI for use

Expected time: 2-3 minutes depending on your internet connection

Step 3: Verify Installation

Check that Astrolock is working:

# From the astrolock directory
./bin/astrolock version

Expected output:

Astrolock v0.1.0

If you see a version number, congratulations! Astrolock is installed correctly.

Troubleshooting Verification

“command not found”

  • Make sure you’re in the astrolock directory
  • Try: cd /path/to/astrolock && ./bin/astrolock version

“Permission denied”

chmod +x ./bin/astrolock
./bin/astrolock version

“Node version error”

# Check your Node version
node --version

# If it's below v18, install Node 18
nvm install 18
nvm use 18

Step 4: Optional - Add to PATH

For convenience, add Astrolock to your PATH so you can run astrolock from anywhere:

macOS / Linux

# For Bash users
echo 'export PATH="/path/to/astrolock-template/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# For Zsh users (macOS default)
echo 'export PATH="/path/to/astrolock-template/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Replace /path/to/astrolock with the actual path. To find it:

cd astrolock
pwd  # Shows full path

Test PATH Setup

# Should work from any directory now
astrolock version

Step 5: Install Optional Dependencies

For enhanced functionality:

lame & ffmpeg (For audio processing)

Required if you plan to use the Rekordbox plugin or process audio files.

# macOS
brew install lame ffmpeg

# Linux (Ubuntu/Debian)
sudo apt-get install lame ffmpeg

# Linux (Fedora)
sudo dnf install lame ffmpeg

jq (For better JSON handling)

Improves JSON parsing in scripts:

# macOS
brew install jq

# Linux
sudo apt-get install jq  # Ubuntu/Debian
sudo dnf install jq      # Fedora

Next Steps

Now that Astrolock is installed:

  1. Create Your First Site - Follow the complete walkthrough
  2. Initialize a site: 
    mkdir my-site
cd my-site
astrolock init
  3. Explore commands: 
    astrolock --help

Common Installation Issues

Node.js Version Issues

Problem: “Unsupported Node.js version”

Solution:

# Check version
node --version

# If below v18, upgrade
nvm install 18
nvm use 18

Permission Errors

Problem: “EACCES: permission denied”

Solution:

# Don't use sudo with yarn
# Instead, fix npm permissions:
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Yarn Not Found

Problem: “yarn: command not found”

Solution:

npm install -g yarn

Git Not Installed

Problem: “git: command not found”

Solution:

# macOS
brew install git

# Linux
sudo apt-get install git  # Ubuntu/Debian
sudo dnf install git      # Fedora

Slow Installation

Problem: yarn install takes a very long time

Solution:

  • Check your internet connection
  • Try using a different network
  • Use yarn cache: yarn install --frozen-lockfile

Uninstalling Astrolock

If you need to remove Astrolock:

# 1. Remove from PATH (if you added it)
# Edit ~/.bashrc or ~/.zshrc and remove the PATH line

# 2. Delete the directory
rm -rf /path/to/astrolock

# 3. Optional: Clean global yarn cache
yarn cache clean

Updating Astrolock

To update to the latest version:

cd /path/to/astrolock
git pull
yarn install

Check the version:

astrolock version

Getting Help

Installation Problems?

  • Check Troubleshooting Guide (coming soon)
  • Review error messages carefully
  • Ensure all prerequisites are met

Ready to Build?

  • Continue to First Steps
  • Run astrolock --help to see all commands

Next: Your First Steps →