> ## Documentation Index
> Fetch the complete documentation index at: https://dos.dzaleka.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started

> Set up your local development environment for Dzaleka Online Services

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

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

## Installation

<Steps>
  ### Clone the repository

  First, clone the Dzaleka Online Services repository to your local machine:

  ```bash theme={null}
  git clone https://github.com/your-org/dzaleka-heritage-archive.git
  cd dzaleka-heritage-archive
  ```

  ### Install dependencies

  Install the project dependencies using your preferred package manager:

  <CodeGroup>
    ```bash npm theme={null}
    npm install
    ```

    ```bash yarn theme={null}
    yarn install
    ```

    ```bash pnpm theme={null}
    pnpm install
    ```
  </CodeGroup>

  ### Set up environment variables

  Create a `.env` file in the root directory and configure your environment variables. See the [Environment Variables](/deployment/environment-variables) page for details.

  ```bash theme={null}
  cp .env.example .env
  ```

  Edit the `.env` file with your configuration values.

  ### Start the development server

  Run the development server:

  <CodeGroup>
    ```bash npm theme={null}
    npm run dev
    ```

    ```bash yarn theme={null}
    yarn dev
    ```

    ```bash pnpm theme={null}
    pnpm dev
    ```
  </CodeGroup>

  The development server will start at `http://localhost:4321` by default.
</Steps>

## 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

<Steps>
  ### Build the project

  Create a production build:

  <CodeGroup>
    ```bash npm theme={null}
    npm run build
    ```

    ```bash yarn theme={null}
    yarn build
    ```

    ```bash pnpm theme={null}
    pnpm build
    ```
  </CodeGroup>

  This will:

  * Compile all Astro pages and components
  * Process Tailwind CSS styles
  * Optimize images and assets
  * Generate static HTML files in the `dist/` directory

  ### Preview the build

  Test your production build locally:

  <CodeGroup>
    ```bash npm theme={null}
    npm run preview
    ```

    ```bash yarn theme={null}
    yarn preview
    ```

    ```bash pnpm theme={null}
    pnpm preview
    ```
  </CodeGroup>
</Steps>

## 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

<CardGroup cols={2}>
  <Card title="Environment Variables" icon="key" href="/deployment/environment-variables">
    Configure required environment variables for your setup
  </Card>

  <Card title="Configuration" icon="gear" href="/deployment/configuration">
    Learn about Astro and Tailwind configuration options
  </Card>

  <Card title="Deploy to Netlify" icon="rocket" href="/deployment/netlify">
    Deploy your site to Netlify in minutes
  </Card>

  <Card title="Custom Domain" icon="globe" href="/deployment/custom-domain">
    Set up a custom domain for your deployment
  </Card>
</CardGroup>

## Troubleshooting

### Port already in use

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

```bash theme={null}
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:

```bash theme={null}
node --version
```

Consider using [nvm](https://github.com/nvm-sh/nvm) to manage Node.js versions:

```bash theme={null}
nvm install 20
nvm use 20
```