Rustelo/content/docs/getting-started.md

title, slug, name, author, content_type, content_format, container, state, require_login, date_init, tags, category, excerpt, seo_title, seo_description, allow_comments, sort_order, metadata

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

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

Installing Node.js

Download and install Node.js from nodejs.org or use a version manager like nvm:

# 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

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:

cp .env.example .env

Edit the .env file with your configuration:

# 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:

# Create database (adjust for your setup)
createdb your_database_name

# Run migrations
cargo install sqlx-cli
sqlx migrate run

4. Install Dependencies

# Install Rust dependencies
cargo build

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

Quick Start

1. Start the Development Server

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:

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

# 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

# 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

# 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:

# 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:

# 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

# 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:

# 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

# 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

# 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

# Find process using port 3000
lsof -i :3000

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

Permission Issues

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

Log Analysis

Enable detailed logging for debugging:

# 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 - Learn about user roles and permissions
2. Content Creation - Deep dive into content management
3. API Reference - Explore all available endpoints
4. Deployment Guide - Deploy to production
5. Security Best Practices - Secure your application

Additional Resources

• API Documentation - Complete API reference
• Configuration Guide - Detailed configuration options
• Performance Tuning - Optimize your application
• Contributing Guide - 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.