Rustelo/content/docs/getting-started.md

---
title: "Getting Started Guide"
slug: "getting-started"
name: "getting-started"
author: "Documentation Team"
content_type: "documentation"
content_format: "markdown"
container: "docs-container"
state: "published"
require_login: false
date_init: "2024-01-10T09:00:00Z"
tags: ["documentation", "getting-started", "tutorial", "setup"]
category: "documentation"
excerpt: "Learn how to get started with our platform. Complete setup guide, installation instructions, and first steps to get you up and running quickly."
seo_title: "Getting Started - Complete Setup Guide"
seo_description: "Complete getting started guide with installation instructions, setup steps, and examples to help you begin using our platform effectively."
allow_comments: false
sort_order: 1
metadata:
  reading_time: "5"
  difficulty: "beginner"
  last_updated: "2024-01-10"
  section: "basics"
---

# Getting Started Guide

Welcome to our platform! This guide will help you get up and running quickly with all the essential features and functionality.

## Prerequisites

Before you begin, make sure you have the following installed on your system:

- **Rust** (version 1.75 or later)
- **Node.js** (version 18 or later)
- **PostgreSQL** (version 14 or later)
- **Git** for version control

### Installing Rust

If you don't have Rust installed, visit [rustup.rs](https://rustup.rs/) and follow the installation instructions for your operating system.

```bash
# Verify your Rust installation
rustc --version
cargo --version
```

### Installing Node.js

Download and install Node.js from [nodejs.org](https://nodejs.org/) or use a version manager like `nvm`:

```bash
# Using nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 18
nvm use 18
```

## Installation

### 1. Clone the Repository

```bash
git clone https://github.com/your-org/your-project.git
cd your-project
```

### 2. Environment Setup

Copy the example environment file and configure your settings:

```bash
cp .env.example .env
```

Edit the `.env` file with your configuration:

```env
# Database Configuration
DATABASE_URL=postgres://username:password@localhost/database_name

# Server Configuration
SERVER_HOST=127.0.0.1
SERVER_PORT=3000
SERVER_PROTOCOL=http

# JWT Configuration
JWT_SECRET=your-super-secret-jwt-key
JWT_EXPIRATION=24h

# OAuth Configuration (optional)
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret
```

### 3. Database Setup

Create your PostgreSQL database and run migrations:

```bash
# Create database (adjust for your setup)
createdb your_database_name

# Run migrations
cargo install sqlx-cli
sqlx migrate run
```

### 4. Install Dependencies

```bash
# Install Rust dependencies
cargo build

# Install Node.js dependencies (if using frontend build tools)
npm install
```

## Quick Start

### 1. Start the Development Server

```bash
cargo run
```

The server will start on `http://localhost:3000` by default.

### 2. Access the Application

Open your web browser and navigate to:
- **Main Application**: `http://localhost:3000`
- **API Documentation**: `http://localhost:3000/api/docs` (if enabled)
- **Health Check**: `http://localhost:3000/health`

### 3. Create Your First User

You can create a user account through the registration endpoint:

```bash
curl -X POST http://localhost:3000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "email": "admin@example.com",
    "password": "SecurePassword123!",
    "display_name": "Administrator"
  }'
```

## Basic Usage

### Authentication

Our platform supports multiple authentication methods:

#### 1. Username/Password Authentication

```bash
# Login with username and password
curl -X POST http://localhost:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "SecurePassword123!"
  }'
```

#### 2. OAuth Integration

We support OAuth with popular providers:
- Google OAuth
- GitHub OAuth
- Discord OAuth

Visit `/api/auth/oauth/{provider}/authorize` to initiate OAuth flow.

### Content Management

#### Creating Content

```bash
# Create a new blog post
curl -X POST http://localhost:3000/api/content/contents \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "slug": "my-first-post",
    "title": "My First Blog Post",
    "name": "first-post",
    "content_type": "blog",
    "content": "# Welcome\n\nThis is my first blog post!",
    "container": "blog-container",
    "state": "published"
  }'
```

#### Retrieving Content

```bash
# Get content by slug
curl http://localhost:3000/api/content/contents/slug/my-first-post

# Get rendered HTML
curl http://localhost:3000/api/content/contents/slug/my-first-post/render

# List all published content
curl http://localhost:3000/api/content/contents/published
```

## Configuration Options

### Server Configuration

The server can be configured through environment variables or a configuration file:

```toml
# config/server.toml
[server]
host = "127.0.0.1"
port = 3000
protocol = "http"

[database]
url = "postgres://localhost/myapp"
max_connections = 10

[security]
jwt_secret = "your-secret-key"
cors_origins = ["http://localhost:3000"]
rate_limit_requests = 1000
rate_limit_window = 3600
```

### Content Configuration

Configure content sources and behavior:

```toml
# config/content.toml
[content]
source = "database"  # or "files" or "both"
file_path = "./content"
enable_cache = true
default_container = "page-container"

[rendering]
enable_syntax_highlighting = true
enable_tables = true
enable_footnotes = true
theme = "base16-ocean.dark"
```

## Development Workflow

### 1. Making Changes

```bash
# Create a new feature branch
git checkout -b feature/my-new-feature

# Make your changes
# ... edit files ...

# Run tests
cargo test

# Check formatting
cargo fmt --check

# Run lints
cargo clippy
```

### 2. Database Migrations

When you need to modify the database schema:

```bash
# Create a new migration
sqlx migrate add create_my_table

# Edit the generated migration file
# migrations/YYYYMMDDHHMMSS_create_my_table.sql

# Run the migration
sqlx migrate run
```

### 3. Running Tests

```bash
# Run all tests
cargo test

# Run tests with output
cargo test -- --nocapture

# Run specific test
cargo test test_name

# Run integration tests
cargo test --test integration_tests
```

## Troubleshooting

### Common Issues

#### Database Connection Issues

```bash
# Check if PostgreSQL is running
pg_isready

# Check database exists
psql -l | grep your_database_name

# Test connection
psql $DATABASE_URL -c "SELECT 1;"
```

#### Port Already in Use

```bash
# Find process using port 3000
lsof -i :3000

# Kill the process (replace PID)
kill -9 PID
```

#### Permission Issues

```bash
# Fix file permissions
chmod +x target/debug/your-app
chmod -R 755 content/
```

### Log Analysis

Enable detailed logging for debugging:

```bash
# Set log level
export RUST_LOG=debug

# Run with logging
cargo run
```

### Getting Help

If you encounter issues:

1. **Check the logs** for error messages
2. **Review the documentation** for your specific use case
3. **Search existing issues** on GitHub
4. **Create a new issue** with detailed information
5. **Join our community** on Discord for real-time help

## Next Steps

Now that you have the basics working, here are some recommended next steps:

1. **[User Management](user-management.md)** - Learn about user roles and permissions
2. **[Content Creation](content-creation.md)** - Deep dive into content management
3. **[API Reference](api-reference.md)** - Explore all available endpoints
4. **[Deployment Guide](deployment.md)** - Deploy to production
5. **[Security Best Practices](security.md)** - Secure your application

## Additional Resources

- **[API Documentation](api-reference.md)** - Complete API reference
- **[Configuration Guide](configuration.md)** - Detailed configuration options
- **[Performance Tuning](performance.md)** - Optimize your application
- **[Contributing Guide](contributing.md)** - How to contribute to the project

---

*This guide gets you started quickly. For more detailed information, explore the other documentation sections or check out our [FAQ](faq.md).*