rweb_starterkit/docs/installation.md

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.
• 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

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:

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:

[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

cargo build

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

Step 4: Run the Application

Development Mode

cargo run

Production Mode

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

You can also specify a custom port:

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:

   # 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 to learn how to use the application.
2. Check the Views Guide to learn how to create and customize views.
3. Set up Gitea Authentication to enable login with Gitea.

Advanced Configuration

For advanced configuration options, please refer to the Configuration Guide.