Getting Started

This guide will help you set up and run Dzaleka Online Services locally on your machine.

Prerequisites

Before you begin, ensure you have the following installed:

Node.js: Version 20 or higher (as specified in netlify.toml:34)
npm, yarn, or pnpm: Package manager of your choice
Git: For version control

The project uses Node.js 20 in production. We recommend matching this version locally to avoid compatibility issues.

Installation

Available Scripts

The following npm scripts are available in package.json:5-12:

Script	Command	Description
`dev`	`astro dev`	Start the development server with hot reload
`start`	`node ./dist/server/entry.mjs`	Start the production server
`build`	`astro build`	Build the site for production
`preview`	`astro preview`	Preview the production build locally
`generate-sitemap`	`node scripts/generate-sitemap.js`	Generate the sitemap.xml file

Building for Production

Project Structure

Understanding the project structure will help you navigate the codebase:

dzaleka-heritage-archive/
├── src/
│   ├── content/          # Content collections (events, stories, jobs, etc.)
│   ├── components/       # Reusable Astro/React components
│   ├── layouts/          # Page layouts
│   ├── pages/            # Route pages
│   └── styles/           # Global styles
├── netlify/
│   └── functions/        # Serverless functions
├── public/               # Static assets
├── astro.config.mjs      # Astro configuration
├── tailwind.config.cjs   # Tailwind CSS configuration
└── netlify.toml          # Netlify deployment configuration

Next Steps

Environment Variables

Configure required environment variables for your setup

Configuration

Learn about Astro and Tailwind configuration options

Deploy to Netlify

Deploy your site to Netlify in minutes

Custom Domain

Set up a custom domain for your deployment

Troubleshooting

Port already in use

If port 4321 is already in use, you can specify a different port:

npm run dev -- --port 3000

Build errors

If you encounter build errors, try:

Delete node_modules/ and package-lock.json
Clear Astro cache: rm -rf .astro
Reinstall dependencies: npm install
Rebuild: npm run build

Node version issues

Ensure you’re using Node.js 20 or higher:

node --version

Consider using nvm to manage Node.js versions:

nvm install 20
nvm use 20

Setup

Hosting

Prerequisites

Installation

Available Scripts

Building for Production

Project Structure

Next Steps

Environment Variables

Configuration

Deploy to Netlify

Custom Domain

Troubleshooting

Port already in use

Build errors

Node version issues

​Prerequisites

​Installation

​Available Scripts

​Building for Production

​Project Structure

​Next Steps

Environment Variables

Configuration

Deploy to Netlify

Custom Domain

​Troubleshooting

​Port already in use

​Build errors

​Node version issues

Prerequisites

Installation

Available Scripts

Building for Production

Project Structure

Next Steps

Troubleshooting

Port already in use

Build errors

Node version issues