337 lines
9.5 KiB
HTML
337 lines
9.5 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="UTF-8">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
<title>Getting Started - WebServ Documentation</title>
|
|
<link rel="stylesheet" href="../css/style.css">
|
|
<style>
|
|
.docs-container {
|
|
max-width: 800px;
|
|
margin: 0 auto;
|
|
padding: 6rem 2rem 4rem;
|
|
}
|
|
.docs-nav {
|
|
background: var(--surface-color);
|
|
padding: 1rem;
|
|
border-radius: 0.5rem;
|
|
margin-bottom: 2rem;
|
|
border: 1px solid var(--border-color);
|
|
}
|
|
.docs-nav ul {
|
|
list-style: none;
|
|
margin: 0;
|
|
padding: 0;
|
|
}
|
|
.docs-nav li {
|
|
margin: 0.5rem 0;
|
|
}
|
|
.docs-nav a {
|
|
color: var(--text-secondary);
|
|
text-decoration: none;
|
|
transition: color 0.3s ease;
|
|
}
|
|
.docs-nav a:hover {
|
|
color: var(--primary-color);
|
|
}
|
|
.code-block {
|
|
background: var(--surface-color);
|
|
border: 1px solid var(--border-color);
|
|
border-radius: 0.5rem;
|
|
padding: 1.5rem;
|
|
margin: 1.5rem 0;
|
|
font-family: 'Fira Code', monospace;
|
|
overflow-x: auto;
|
|
}
|
|
.warning {
|
|
background: rgba(245, 158, 11, 0.1);
|
|
border: 1px solid var(--warning-color);
|
|
border-radius: 0.5rem;
|
|
padding: 1rem;
|
|
margin: 1.5rem 0;
|
|
}
|
|
.info {
|
|
background: rgba(37, 99, 235, 0.1);
|
|
border: 1px solid var(--primary-color);
|
|
border-radius: 0.5rem;
|
|
padding: 1rem;
|
|
margin: 1.5rem 0;
|
|
}
|
|
</style>
|
|
</head>
|
|
<body>
|
|
<nav class="navbar">
|
|
<div class="nav-container">
|
|
<div class="nav-logo">
|
|
<h2><a href="../index.html" style="color: var(--primary-color); text-decoration: none;">WebServ</a></h2>
|
|
</div>
|
|
<div class="nav-menu">
|
|
<a href="../index.html#home" class="nav-link">Home</a>
|
|
<a href="../index.html#features" class="nav-link">Features</a>
|
|
<a href="../index.html#documentation" class="nav-link">Documentation</a>
|
|
<a href="../index.html#demo" class="nav-link">Demo</a>
|
|
</div>
|
|
</div>
|
|
</nav>
|
|
|
|
<div class="docs-container">
|
|
<h1>Getting Started with WebServ</h1>
|
|
|
|
<nav class="docs-nav">
|
|
<ul>
|
|
<li><a href="#installation">Installation</a></li>
|
|
<li><a href="#configuration">Basic Configuration</a></li>
|
|
<li><a href="#running">Running the Server</a></li>
|
|
<li><a href="#testing">Testing Your Setup</a></li>
|
|
<li><a href="#troubleshooting">Troubleshooting</a></li>
|
|
</ul>
|
|
</nav>
|
|
|
|
<section id="installation">
|
|
<h2>Installation</h2>
|
|
<p>WebServ is built with modern C++20 and requires a recent compiler and CMake for building.</p>
|
|
|
|
<h3>Prerequisites</h3>
|
|
<ul>
|
|
<li>C++20 compatible compiler (GCC 10+, Clang 12+)</li>
|
|
<li>CMake 3.22 or higher</li>
|
|
<li>Make build system</li>
|
|
<li>Linux operating system (epoll-based)</li>
|
|
</ul>
|
|
|
|
<h3>Building from Source</h3>
|
|
<div class="code-block">
|
|
<pre># Clone the repository
|
|
git clone https://github.com/WHaffmans/webserv.git
|
|
cd webserv
|
|
|
|
# Build the project
|
|
make
|
|
|
|
# Or build with specific configuration
|
|
make build_type=release
|
|
make build_type=debug
|
|
make build_type=asan</pre>
|
|
</div>
|
|
|
|
<div class="info">
|
|
<strong>💡 Build Types:</strong><br>
|
|
• <code>debug</code>: Debug symbols, no optimization<br>
|
|
• <code>release</code>: Optimized build for production<br>
|
|
• <code>asan</code>: Address sanitizer for memory debugging
|
|
</div>
|
|
</section>
|
|
|
|
<section id="configuration">
|
|
<h2>Basic Configuration</h2>
|
|
<p>WebServ uses nginx-style configuration files for maximum flexibility and familiarity.</p>
|
|
|
|
<h3>Minimal Configuration</h3>
|
|
<div class="code-block">
|
|
<pre># webserv.conf
|
|
server {
|
|
listen 8080;
|
|
server_name localhost;
|
|
root ./www;
|
|
index index.html;
|
|
|
|
location / {
|
|
try_files $uri $uri/ =404;
|
|
}
|
|
}</pre>
|
|
</div>
|
|
|
|
<h3>Advanced Configuration</h3>
|
|
<div class="code-block">
|
|
<pre># Advanced webserv.conf
|
|
server {
|
|
listen 80;
|
|
server_name example.com www.example.com;
|
|
root /var/www/html;
|
|
index index.html index.htm;
|
|
|
|
# Error pages
|
|
error_page 404 /404.html;
|
|
error_page 500 502 503 504 /50x.html;
|
|
|
|
# Static files with caching
|
|
location /static/ {
|
|
expires 1y;
|
|
add_header Cache-Control "public, immutable";
|
|
}
|
|
|
|
# API endpoints
|
|
location /api/ {
|
|
proxy_pass http://127.0.0.1:3000;
|
|
proxy_set_header Host $host;
|
|
proxy_set_header X-Real-IP $remote_addr;
|
|
}
|
|
|
|
# Directory listing
|
|
location /files/ {
|
|
autoindex on;
|
|
autoindex_exact_size off;
|
|
}
|
|
}
|
|
|
|
# HTTPS server
|
|
server {
|
|
listen 443 ssl;
|
|
server_name example.com;
|
|
|
|
ssl_certificate /path/to/cert.pem;
|
|
ssl_certificate_key /path/to/key.pem;
|
|
|
|
root /var/www/ssl;
|
|
index index.html;
|
|
}</pre>
|
|
</div>
|
|
</section>
|
|
|
|
<section id="running">
|
|
<h2>Running the Server</h2>
|
|
|
|
<h3>Basic Usage</h3>
|
|
<div class="code-block">
|
|
<pre># Run with default configuration
|
|
./build/webserv
|
|
|
|
# Run with custom configuration file
|
|
./build/webserv config/webserv.conf
|
|
|
|
# Run with make target (rebuilds if needed)
|
|
make run</pre>
|
|
</div>
|
|
|
|
<h3>Command Line Options</h3>
|
|
<div class="code-block">
|
|
<pre>Usage: webserv [config_file]
|
|
|
|
Arguments:
|
|
config_file Path to configuration file (default: webserv.conf)
|
|
|
|
Examples:
|
|
./webserv # Use default config
|
|
./webserv /etc/webserv.conf # Use specific config
|
|
./webserv --help # Show help message</pre>
|
|
</div>
|
|
|
|
<div class="warning">
|
|
<strong>⚠️ Important:</strong> Make sure the specified ports are not already in use. WebServ will fail to start if the ports are occupied.
|
|
</div>
|
|
</section>
|
|
|
|
<section id="testing">
|
|
<h2>Testing Your Setup</h2>
|
|
|
|
<h3>Basic Connectivity Test</h3>
|
|
<div class="code-block">
|
|
<pre># Test with curl
|
|
curl http://localhost:8080/
|
|
|
|
# Test with specific headers
|
|
curl -H "Host: example.com" http://localhost:8080/
|
|
|
|
# Test POST request
|
|
curl -X POST -d "test=data" http://localhost:8080/api/test</pre>
|
|
</div>
|
|
|
|
<h3>Performance Testing</h3>
|
|
<div class="code-block">
|
|
<pre># Apache Bench
|
|
ab -n 1000 -c 10 http://localhost:8080/
|
|
|
|
# wrk load testing
|
|
wrk -t12 -c400 -d30s http://localhost:8080/
|
|
|
|
# siege testing
|
|
siege -c 50 -t 30s http://localhost:8080/</pre>
|
|
</div>
|
|
|
|
<h3>Running Unit Tests</h3>
|
|
<div class="code-block">
|
|
<pre># Build and run tests
|
|
make test
|
|
|
|
# Run specific test suite
|
|
cd build && ctest -V
|
|
|
|
# Run with Google Test directly
|
|
./build/webserv_tests</pre>
|
|
</div>
|
|
</section>
|
|
|
|
<section id="troubleshooting">
|
|
<h2>Troubleshooting</h2>
|
|
|
|
<h3>Common Issues</h3>
|
|
|
|
<h4>Port Already in Use</h4>
|
|
<div class="code-block">
|
|
<pre># Check what's using the port
|
|
sudo netstat -tlnp | grep :8080
|
|
sudo lsof -i :8080
|
|
|
|
# Kill process using the port
|
|
sudo kill -9 <PID></pre>
|
|
</div>
|
|
|
|
<h4>Permission Denied</h4>
|
|
<div class="code-block">
|
|
<pre># For ports below 1024, run as root
|
|
sudo ./build/webserv
|
|
|
|
# Or use a port above 1024
|
|
# Edit config: listen 8080;</pre>
|
|
</div>
|
|
|
|
<h4>Configuration Errors</h4>
|
|
<div class="code-block">
|
|
<pre># Check configuration syntax
|
|
./build/webserv -t config/webserv.conf
|
|
|
|
# Debug mode for detailed logging
|
|
./build/webserv_debug config/webserv.conf</pre>
|
|
</div>
|
|
|
|
<h3>Log Files</h3>
|
|
<p>WebServ logs are written to both console and log files:</p>
|
|
<div class="code-block">
|
|
<pre># Default log locations
|
|
./logs/access.log # Access logs
|
|
./logs/error.log # Error logs
|
|
./logs/debug.log # Debug logs (debug build only)
|
|
|
|
# Tail logs in real-time
|
|
tail -f logs/access.log
|
|
tail -f logs/error.log</pre>
|
|
</div>
|
|
|
|
<h3>Debug Build</h3>
|
|
<p>For development and troubleshooting, use the debug build:</p>
|
|
<div class="code-block">
|
|
<pre># Build debug version
|
|
make build_type=debug
|
|
|
|
# Run with debug logging
|
|
./build/webserv_debug
|
|
|
|
# Use with GDB for debugging
|
|
gdb ./build/webserv_debug
|
|
(gdb) run config/webserv.conf</pre>
|
|
</div>
|
|
|
|
<div class="info">
|
|
<strong>💡 Pro Tip:</strong> Use the address sanitizer build (<code>make build_type=asan</code>) to catch memory errors during development.
|
|
</div>
|
|
</section>
|
|
|
|
<hr style="margin: 3rem 0; border: 1px solid var(--border-color);">
|
|
|
|
<div style="text-align: center;">
|
|
<p>Need more help? Check out the <a href="configuration.html" style="color: var(--primary-color);">Configuration Guide</a> or <a href="api.html" style="color: var(--primary-color);">API Reference</a>.</p>
|
|
</div>
|
|
</div>
|
|
</body>
|
|
</html>
|