645a387528
- Add `.env.template` file for environment variable configuration. - Add `.gitignore` file to ignore generated files and IDE artifacts. - Add `Cargo.toml` file specifying project dependencies. - Add basic project documentation in `README.md` and configuration guide in `docs/configuration.md`. - Add Gitea authentication guide in `docs/gitea-auth.md`. - Add installation guide in `docs/installation.md`. - Add MVC architecture guide in `docs/mvc.md`. - Add views guide in `docs/views.md`.
130 lines
3.0 KiB
Markdown
130 lines
3.0 KiB
Markdown
# 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).
|