npm package: @serverduty/httpd
Description: ServerDuty HTTPD
Author: ServerDuty
Latest version: 0.2.0

# httpd

[![github stars](https://img.shields.io/github/stars/serverduty/httpd)](https://github.com/serverduty/httpd) [![npm version](https://img.shields.io/npm/v/@serverduty/httpd)](https://www.npmjs.com/package/@serverduty/httpd) [![npm downloads](https://img.shields.io/npm/dt/@serverduty/httpd)](https://www.npmjs.com/package/@serverduty/httpd)

`@serverduty/httpd` is a straightforward, highly configurable HTTP server built with Node.js and Express. It's designed for serving static files with optional IP-based access control. Below, we'll walk you through setting up a basic "Hello World" website and running it with `@serverduty/httpd`.

### Prerequisites

Before you begin, ensure you have Node.js installed on your system. You can download and install Node.js from [here](https://nodejs.org/).

### Step 1: Installation

First, install `@serverduty/httpd` globally using npm:

```sh
npm install -g @serverduty/httpd
```

This command makes the `sdhttpd` command available globally.

### Step 2: Setting Up Your Website

Create a new directory for your website and navigate into it:

```sh
mkdir my-website
cd my-website
```

Create a simple `index.html` file:

```html
<!DOCTYPE html>
<html>
<head>
  <title>Hello World</title>
</head>
<body>
  <h1>Hello World!</h1>
</body>
</html>
```

### Step 3: Running the Server

Run `sdhttpd` to start serving your website:

```sh
sdhttpd
```

By default, the server listens on port 8000 and serves files from the `www` directory in the current working directory.

### Step 4: Accessing Your Website

Open a web browser and navigate to `http://localhost:8000`. You should see your "Hello World" page.

### Configuration Options

`@serverduty/httpd` can be configured using environment variables. Here are the available options:

- `HTTP_ROOT_DIR`: The directory from which to serve files. Defaults to `www` in the current working directory.
- `HTTP_PORT`: The port on which the server listens. Defaults to `8000`.
- `HTTP_ACCESS_LIST`: A comma-separated list of IP addresses allowed to access the server. If not set, all IPs are allowed.
- `HTTP_LOG_FORMAT`: The format of the logs (options: `combined`, `common`, `dev`, `short`, `tiny`). Defaults to `common`.
- `HTTP_REMOTE_IP_HEADER`: The name of the header containing the remote IP address. Defaults to `x-forwarded-for`.

Example of setting environment variables:

```sh
export HTTP_PORT=9000
export HTTP_ROOT_DIR=/path/to/your/site
export HTTP_ACCESS_LIST='192.168.1.1,192.168.1.2'
export HTTP_LOG_FORMAT='combined'
export HTTP_REMOTE_IP_HEADER='x-forwarded-for'
```

Then run the server:

```sh
sdhttpd
```

Alternatively, you can set the environment variables inline, for example:

```sh
HTTP_PORT=9000 HTTP_ROOT_DIR=/path/to/your/site sdhttpd
```

### Step 5: Custom Error Pages

To use custom error pages, simply add `404.html`, `500.html`, etc., to your `HTTP_ROOT_DIR`. The server will serve these pages when the corresponding HTTP errors occur.

### Conclusion

You've now set up a basic static website served by `@serverduty/httpd`. This server is suitable for quickly hosting static content with optional IP-based access control, customizable logging, and custom error pages.

## License

The MIT License (MIT)

Copyright 2023 ServerDuty Limited

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.