Skip to main content
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

1
Clone the repository
2
First, clone the Dzaleka Online Services repository to your local machine:
3
git clone https://github.com/your-org/dzaleka-heritage-archive.git
cd dzaleka-heritage-archive
4
Install dependencies
5
Install the project dependencies using your preferred package manager:
6
npm
npm install
yarn
yarn install
pnpm
pnpm install
7
Set up environment variables
8
Create a .env file in the root directory and configure your environment variables. See the Environment Variables page for details.
9
cp .env.example .env
10
Edit the .env file with your configuration values.
11
Start the development server
12
Run the development server:
13
npm
npm run dev
yarn
yarn dev
pnpm
pnpm dev
14
The development server will start at http://localhost:4321 by default.

​
Available Scripts

The following npm scripts are available in package.json:5-12:
ScriptCommandDescription
devastro devStart the development server with hot reload
startnode ./dist/server/entry.mjsStart the production server
buildastro buildBuild the site for production
previewastro previewPreview the production build locally
generate-sitemapnode scripts/generate-sitemap.jsGenerate the sitemap.xml file

​
Building for Production

1
Build the project
2
Create a production build:
3
npm
npm run build
yarn
yarn build
pnpm
pnpm build
4
This will:
5
  • Compile all Astro pages and components
  • Process Tailwind CSS styles
  • Optimize images and assets
  • Generate static HTML files in the dist/ directory
    • 6
    Preview the build
    7
    Test your production build locally:
    8
    npm
    npm run preview
    yarn
    yarn preview
    pnpm
    pnpm preview

    ​
    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:
    1. Delete node_modules/ and package-lock.json
    2. Clear Astro cache: rm -rf .astro
    3. Reinstall dependencies: npm install
    4. 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