# Installation Guide

This guide provides detailed instructions for installing and setting up the Hostbasket application.

## Prerequisites

Before you begin, ensure you have the following installed:

- **Rust and Cargo**: The latest stable version is recommended. You can install Rust using [rustup](https://rustup.rs/).
- **Git**: For cloning the repository.
- **A text editor or IDE**: Such as Visual Studio Code, IntelliJ IDEA with Rust plugin, or any other editor of your choice.

## Step 1: Clone the Repository

```bash
git clone https://git.ourworld.tf/herocode/rweb_starterkit
cd rweb_starterkit
```

## Step 2: Configure the Application

The application can be configured using environment variables or configuration files.

### Using Environment Variables

You can set the following environment variables:

```bash
export APP__SERVER__HOST=127.0.0.1
export APP__SERVER__PORT=9999
export APP__SERVER__WORKERS=4
export APP__TEMPLATES__DIR=./src/views
export JWT_SECRET=your_jwt_secret_key
```

### Using Configuration Files

Alternatively, you can create a configuration file in the `config` directory:

1. Create a file named `config/default.toml` with the following content:

```toml
[server]
host = "127.0.0.1"
port = 9999
workers = 4

[templates]
dir = "./src/views"
```

2. You can also create environment-specific configuration files like `config/development.toml` or `config/production.toml`.

## Step 3: Build the Project

```bash
cargo build
```

This will download and compile all dependencies and build the project.

## Step 4: Run the Application

### Development Mode

```bash
cargo run
```

### Production Mode

```bash
cargo build --release
./target/release/hostbasket
```

You can also specify a custom port:

```bash
cargo run -- --port 8080
```

## Step 5: Verify the Installation

Open your web browser and navigate to `http://localhost:9999` (or the port you specified). You should see the Hostbasket home page.

## Troubleshooting

### Common Issues

1. **Port already in use**:
   ```
   Error: Address already in use (os error 98)
   ```
   Solution: Change the port using the `--port` flag or the `APP__SERVER__PORT` environment variable.

2. **Missing dependencies**:
   ```
   error: failed to run custom build command for `openssl-sys v0.9.58`
   ```
   Solution: Install OpenSSL development libraries:
   ```bash
   # Ubuntu/Debian
   sudo apt-get install libssl-dev pkg-config

   # Fedora/CentOS
   sudo dnf install openssl-devel pkgconfig

   # macOS
   brew install openssl pkg-config
   ```

3. **Template parsing errors**:
   ```
   Parsing error(s): Failed to parse template...
   ```
   Solution: Check your template files for syntax errors.

## Next Steps

After successfully installing the application, you can:

1. Explore the [Usage Guide](usage.md) to learn how to use the application.
2. Check the [Views Guide](views.md) to learn how to create and customize views.
3. Set up [Gitea Authentication](gitea-auth.md) to enable login with Gitea.

## Advanced Configuration

For advanced configuration options, please refer to the [Configuration Guide](configuration.md).