Add documentation

StJudeWasHere · Jan 16, 2025 · 07c8381 · 07c8381
1 parent 1ec42cb
commit 07c8381
Show file tree

Hide file tree

Showing 4 changed files with 239 additions and 13 deletions.
diff --git a/README.md b/README.md
@@ -1,37 +1,54 @@
 # SEOnaut
 [![Go Report Card](https://goreportcard.com/badge/github.com/stjudewashere/seonaut)](https://goreportcard.com/report/github.com/stjudewashere/seonaut) [![GitHub](https://img.shields.io/github/license/StJudeWasHere/seonaut)](LICENSE) [![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/StJudeWasHere/seonaut/test.yml)](https://github.com/StJudeWasHere/seonaut/actions/workflows/test.yml)
 
-SEOnaut is an open source SEO auditing tool that checks your website for any issues that might be affecting your search engine rankings. It will look at your entire site and give you a report with a list of any problems it finds, organized by how important they are to fix.
+SEOnaut is an open-source SEO auditing tool designed to analyze websites for issues that may impact search engine rankings. It performs a comprehensive site scan and generates a report detailing any identified issues, organized by severity and potential impact on SEO.
 
-The issues on your website are organized into three categories based on their level of severity and potential impact on your search engine rankings. SEOnaut can identify broken links to prevent 404 not found errors, temporary or permanent redirects and redirect loops, missing or duplicated meta tags, missing or incorrectly ordered headings and more.
+SEOnaut categorizes issues into three levels of severity: critical, high, and low. The tool can detect various SEO-related problems, such as broken links (to avoid 404 errors), redirect issues (temporary, permanent, or loops), missing or duplicate meta tags, incorrectly ordered headings, and more.
 
 A hosted version of SEOnaut is available at [seonaut.org](https://seonaut.org).
 
 ![seonaut](https://github.com/user-attachments/assets/6184b418-bd54-4456-9266-fcfd4ce5726d)
 
 ## Technology
 
-SEOnaut is a web based application built with the Go programming language and a MySQL database for its data storage. On the frontend side, the user interface is designed with simplicity in mind, using custom CSS and minimal vanilla Javascript. To make the dashboard interactive, the application utilizes Apache ECharts.
+SEOnaut is a web-based application built with the Go programming language and a MySQL database for data storage. The frontend is designed for simplicity, using custom CSS and minimal vanilla JavaScript. Apache ECharts is used to provide an interactive dashboard experience.
 
-While it is possible to configure your own database and compile SEOnaut by yourself, it's generally more convenient to use the provided Docker files. These files streamline the setup process and eliminate the need for manual configuration, allowing you to get started with SEOnaut more quickly and easily.
+While it is possible to configure a custom database and compile SEOnaut manually, using the provided Docker files is recommended. These files simplify the setup process and eliminate the need for manual configuration, allowing for quicker and easier deployment.
 
-### Docker
+### Quick Start Guide
 
-Make sure you have Docker installed on your system. You can download and install Docker from their official website.
+To get started with SEOnaut, follow these steps to run it using Docker:
 
-Run the following command and wait for the Docker images to download and build.
+1. **Install Docker**  
+   Ensure Docker is installed on your system. You can download and install Docker from the [official website](https://www.docker.com/).
 
-```shell
-$ docker-compose up -d --build
-```
+2. **Clone the Repository**  
+   Clone the SEOnaut repository:
 
-Once the process is complete, you can access SEOnaut in your web browser by visiting ```http://localhost:9000```.
+   `git clone https://github.com/stjudewashere/seonaut.git`
 
-SEOnaut is set up to run on port 9000 using unencrypted HTTP by default. However, for security reasons, it is often advisable to run it on HTTPS behind a reverse proxy. This adds an extra layer of protection to the application and ensures that any sensitive data transmitted between the server and the client is encrypted.
+3. **Navigate to the Project Directory**  
+   Change into the project directory:
+
+   `cd seonaut`
+
+4. **Build and Run Docker Containers**  
+   Run the following command to build and start the Docker containers:
+
+   `docker-compose -f docker-compose.yml -f docker-compose.dev.yml up -d --build`
+
+5. **Access the Application**  
+   Once the containers are running, open your browser and visit:
+
+   `http://localhost:9000`
+
+   SEOnaut is set up to run on port 9000 using unencrypted HTTP by default. For added security, it is recommended to configure HTTPS using a reverse proxy. This will ensure encrypted communication between the client and the server.
+
+For more detailed installation and configuration instructions, refer to the [INSTALL.md](docs/INSTALL.md) file.
 
 ## Contributing
 
-Please see [CONTRIBUTING](CONTRIBUTING.md) for details.
+Please see [CONTRIBUTING](docs/CONTRIBUTING.md) for details.
 
 ## License
 

diff --git a/CODE_OF_CONDUCT.md → docs/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md → docs/CODE_OF_CONDUCT.md
diff --git a/CONTRIBUTING.md → docs/CONTRIBUTING.md b/CONTRIBUTING.md → docs/CONTRIBUTING.md
diff --git a/docs/INSTALL.md b/docs/INSTALL.md
@@ -0,0 +1,209 @@
+# INSTALLATION GUIDE
+
+This document provides instructions for installing and configuring SEOnaut. Follow the steps below to set up the application using Docker or by compiling it from source. Instructions for configuring a reverse proxy with HTTPS and WebSocket support are also included.
+
+## Prerequisites
+
+Before installing SEOnaut, ensure the following are installed on your system:
+
+- **Docker**: Install Docker from [docker.com](https://www.docker.com/).
+- **Git**: Required to clone the repository.
+- **Go Programming Language** (optional, if not using Docker): Install Go from [golang.org](https://golang.org/).
+- **Make** (optional): To use the Makefile commands provided in the project.
+- **MySQL Database**: Install and configure a MySQL server (if not using Docker).
+- **Nginx or Apache**: Required to set up a reverse proxy.
+
+---
+
+## Installation Options
+
+### Using Docker
+
+1. **Clone the Repository**  
+   Clone the SEOnaut repository from GitHub:
+
+   `git clone https://github.com/stjudewashere/seonaut.git`
+
+2. **Navigate to the Project Directory**  
+   Move to the project folder:
+
+   `cd seonaut`
+
+3. **Build and Run Docker Containers**  
+   Run docker-compose to build and start the containers:
+
+   `docker-compose -f docker-compose.yml -f docker-compose.dev.yml up -d --build`
+
+   Or use the provided Makefile to build and start the Docker containers:
+
+   `make docker`
+
+4. **Access the Application**  
+   Open your browser and navigate to:
+
+   `http://localhost:9000`
+
+   To secure SEOnaut with HTTPS, set up a reverse proxy as explained below.
+
+---
+
+### Compiling from Source
+
+1. **Clone the Repository**  
+   Clone the SEOnaut repository:
+
+   `git clone https://github.com/stjudewashere/seonaut.git`
+
+2. **Navigate to the Project Directory**  
+   Change into the project directory:
+
+   `cd seonaut`
+
+3. **Run the Application**  
+   Use the Makefile to run the application with the default configuration:
+
+   `make run`
+
+   To use a custom configuration file, specify it with the `-c` option:
+
+   `go run -race cmd/server/main.go -c path/to/your/config`
+
+4. **Access the Application**  
+   Navigate to:
+
+   `http://localhost:9000`
+
+---
+
+## Configuration File
+
+The application uses a configuration file named `config`, located in the root directory. Customize this file to match your environment or specify a custom file using the `-c` option.
+
+### Default Configuration
+
+    [server]
+    host = "0.0.0.0"
+    port = 9000
+    url = "http://localhost:9000"
+
+    [database]
+    server = "db"
+    port = 3306
+    user = "seonaut"
+    password = "seonaut"
+    database = "seonaut"
+
+    [crawler]
+    agent = "Mozilla/5.0 (compatible; SEOnautBot/1.0; +https://seonaut.org/bot)"
+
+### Key Configuration Options
+
+- **[server]**
+  - `host`: IP address to bind the server (default: `0.0.0.0`).
+  - `port`: Port for the server (default: `9000`).
+  - `url`: Base URL of the application, e.g., `https://example.com`.
+
+- **[database]**
+  - `server`: Hostname or IP of the database server.
+  - `port`: Port of the database (default: `3306`).
+  - `user`: Database username.
+  - `password`: Database password.
+  - `database`: Name of the database.
+
+- **[crawler]**
+  - `agent`: User agent string for the crawler.
+
+---
+
+## Setting Up a Reverse Proxy
+
+### Nginx Configuration
+
+1. **Install Nginx**  
+   Install Nginx using your package manager:
+
+   `sudo apt update && sudo apt install nginx`
+
+2. **Create a Configuration File**  
+   Create `/etc/nginx/sites-available/seonaut` with the following content:
+
+    server {
+        listen 80;
+        server_name example.com;
+
+        location / {
+            proxy_pass http://localhost:9000;
+            proxy_http_version 1.1;
+            proxy_set_header Upgrade $http_upgrade;
+            proxy_set_header Connection "upgrade";
+            proxy_set_header Host $host;
+            proxy_cache_bypass $http_upgrade;
+        }
+
+        location /crawl/ws {
+            proxy_pass http://localhost:9000/crawl/ws;
+            proxy_http_version 1.1;
+            proxy_set_header Upgrade $http_upgrade;
+            proxy_set_header Connection "upgrade";
+            proxy_set_header Host $host;
+            proxy_cache_bypass $http_upgrade;
+        }
+    }
+
+3. **Enable HTTPS with Certbot**  
+   Install Certbot and configure HTTPS:
+
+   `sudo apt install certbot python3-certbot-nginx`
+
+   `sudo certbot --nginx -d example.com`
+
+4. **Restart Nginx**  
+   Reload the configuration:
+
+   `sudo systemctl reload nginx`
+
+---
+
+### Apache Configuration
+
+1. **Install Apache**  
+   Install Apache using your package manager:
+
+   `sudo apt update && sudo apt install apache2`
+
+2. **Enable Required Modules**  
+   Enable the necessary Apache modules:
+
+   `sudo a2enmod proxy proxy_http proxy_wstunnel ssl`
+
+3. **Create a Virtual Host File**  
+   Add `/etc/apache2/sites-available/seonaut.conf` with the following content:
+
+    <VirtualHost *:80>
+        ServerName example.com
+
+        ProxyPreserveHost On
+        ProxyRequests Off
+
+        <Location />
+            ProxyPass http://localhost:9000/
+            ProxyPassReverse http://localhost:9000/
+        </Location>
+
+        <Location /crawl/ws>
+            ProxyPass ws://localhost:9000/crawl/ws
+            ProxyPassReverse ws://localhost:9000/crawl/ws
+        </Location>
+    </VirtualHost>
+
+4. **Enable HTTPS with Certbot**  
+   Configure HTTPS:
+
+   `sudo apt install certbot python3-certbot-apache`
+
+   `sudo certbot --apache -d example.com`
+
+5. **Restart Apache**  
+   Reload the configuration:
+
+   `sudo systemctl reload apache2`