mirror of
https://github.com/pommee/goaway.git
synced 2026-01-11 08:31:00 -06:00
docs: add webpage for installation, configuration, setup and more
This commit is contained in:
pommee
5
Makefile
5
Makefile
@@ -1,4 +1,4 @@
|
||||
.PHONY: publish build lint example-queries dev format test bench
|
||||
.PHONY: publish build lint example-queries dev format test bench docs-serve docs-build
|
||||
|
||||
DNS_PORT ?= 53
|
||||
WEBSITE_PORT ?= 8080
|
||||
@@ -35,3 +35,6 @@ test: lint commitlint
|
||||
|
||||
bench: ; go run test/benchmark.go -test.bench=.
|
||||
bench-profile: ; go run test/benchmark.go -test.bench=. & go tool pprof http://localhost:6060/debug/pprof/profile\?seconds\=5
|
||||
|
||||
docs-serve: ; make -C docs serve
|
||||
docs-build: ; make -C docs build
|
||||
|
||||
193
README.md
193
README.md
@@ -9,7 +9,12 @@ A lightweight DNS sinkhole for blocking unwanted domains at the network level. B
|
||||
|
||||
**[View more screenshots](./resources/PREVIEW.md)**
|
||||
|
||||
<<<<<<< HEAD
|
||||
<<<<<<< Updated upstream
|
||||
=======
|
||||
**Instructions on installation, configuration** and more can be found [on the homepage](https://github.com/pommee/goaway).
|
||||
|
||||
>>>>>>> 4619f8f (docs: add webpage for installation, configuration, setup and more)
|
||||
## 🌟 Features
|
||||
=======
|
||||
## Getting started
|
||||
@@ -28,194 +33,6 @@ Instructions for installation, configuration and more can be found on the homepa
|
||||
- Low resource footprint
|
||||
- And much more...
|
||||
|
||||
## 📦 Installation
|
||||
|
||||
### Option 1: Docker Installation (Recommended)
|
||||
|
||||
**Quick Start:**
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
--name goaway \
|
||||
-p 53:53/udp \
|
||||
-p 53:53/tcp \
|
||||
-p 8080:8080 \
|
||||
pommee/goaway:latest
|
||||
```
|
||||
|
||||
**Using Docker Compose (Recommended for production):**
|
||||
|
||||
Data will **not persist** unless volumes are used!
|
||||
|
||||
```yml
|
||||
services:
|
||||
goaway:
|
||||
image: pommee/goaway:latest
|
||||
container_name: goaway
|
||||
restart: unless-stopped
|
||||
# volumes:
|
||||
# - /path/to/config:/app/config # Custom settings.yaml configuration
|
||||
# - /path/to/data:/app/data # Database storage location
|
||||
environment:
|
||||
- DNS_PORT=${DNS_PORT:-53}
|
||||
- WEBSITE_PORT=${WEBSITE_PORT:-8080}
|
||||
# - DOT_PORT=${DOT_PORT:-853} # Port for DoT
|
||||
ports:
|
||||
- "${DNS_PORT:-53}:${DNS_PORT:-53}/udp"
|
||||
- "${DNS_PORT:-53}:${DNS_PORT:-53}/tcp"
|
||||
- "${WEBSITE_PORT:-8080}:${WEBSITE_PORT:-8080}/tcp"
|
||||
# - "${DOT_PORT:-853}:${DOT_PORT:-853}/tcp"
|
||||
cap_add:
|
||||
- NET_BIND_SERVICE
|
||||
- NET_RAW
|
||||
```
|
||||
|
||||
### Option 2: Quick Install
|
||||
|
||||
**Quick Install Script:**
|
||||
|
||||
```bash
|
||||
# Install latest version
|
||||
curl https://raw.githubusercontent.com/pommee/goaway/main/installer.sh | sh
|
||||
|
||||
# Install specific version
|
||||
curl https://raw.githubusercontent.com/pommee/goaway/main/installer.sh | sh /dev/stdin 0.40.4
|
||||
```
|
||||
|
||||
The installer will:
|
||||
|
||||
1. Detect your operating system and architecture
|
||||
2. Download the appropriate binary
|
||||
3. Install it to `~/.local/bin`
|
||||
4. Set up necessary permissions
|
||||
|
||||
**Manual Installation:**
|
||||
Download binaries directly from the [releases page](https://github.com/pommee/goaway/releases).
|
||||
|
||||
### Option 3: Build from Source
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone https://github.com/pommee/goaway.git
|
||||
cd goaway
|
||||
|
||||
# Build the frontend
|
||||
make build
|
||||
|
||||
# Build GoAway binary
|
||||
go build -o goaway
|
||||
|
||||
# Start the service
|
||||
./goaway
|
||||
```
|
||||
|
||||
### Option 4: Proxmox
|
||||
|
||||
If you are planning on running via Proxmox, then there is a helper-script available [here](https://community-scripts.github.io/ProxmoxVE/scripts?id=goaway), created by [Proxmox VE Helper-Scripts (Community Edition)](https://github.com/community-scripts/ProxmoxVE).
|
||||
Great alternative if you don't want to go through an as manual process and prefer not to use Docker.
|
||||
**Tip**: Once the LXC is up and running, logs can be found in `/var/log/goaway.log`. Login credentials can be found either in the log or `~/goaway.creds`.
|
||||
|
||||
## 🚀 Getting Started
|
||||
|
||||
### Basic Usage
|
||||
|
||||
Start GoAway with default settings:
|
||||
|
||||
```bash
|
||||
goaway
|
||||
```
|
||||
|
||||
You'll see a startup message confirming the services are running:
|
||||
|
||||
|
||||
|
||||
> [!IMPORTANT]
|
||||
> **First-time Setup:** GoAway runs in authenticated mode by default and generates a random password on first startup. This password is shown only once in the logs - make sure to save it!
|
||||
|
||||
### Accessing the Dashboard
|
||||
|
||||
1. Open your browser and navigate to `http://your-server-ip:port`
|
||||
2. Default username: `admin`
|
||||
3. Use the generated password from startup
|
||||
|
||||
### Configure Your Devices
|
||||
|
||||
To use GoAway as your DNS server, update your device or router settings:
|
||||
|
||||
**Router Configuration (Recommended):**
|
||||
|
||||
- Set your router's DNS server to GoAway's IP address
|
||||
- This will protect all devices on your network
|
||||
|
||||
**Individual Device:**
|
||||
|
||||
- Update DNS settings to point to GoAway's IP address
|
||||
- Primary DNS: `<goaway-server-ip>`
|
||||
- Secondary DNS: `1.1.1.1` or `8.8.8.8` - Used as a fallback
|
||||
|
||||
### Command Line Options
|
||||
|
||||
```bash
|
||||
goaway --help
|
||||
|
||||
GoAway is a DNS sinkhole with a web interface
|
||||
|
||||
Usage:
|
||||
goaway [flags]
|
||||
|
||||
Flags:
|
||||
-h, --help help for goaway
|
||||
--ansi Toggle colorized logs. Only available in non-json formatted logs (default true)
|
||||
--auth Toggle authentication for admin dashboard (default true)
|
||||
--dashboard Serve dashboard (default true)
|
||||
--dns-port int Port for the DNS server (default 53)
|
||||
--dot-port int Port for the DoT (DNS-over-TCP) server (default 853)
|
||||
--json Toggle JSON formatted logs
|
||||
--log-level int 0 = DEBUG | 1 = INFO | 2 = WARNING | 3 = ERROR (default 1)
|
||||
--logging Toggle logging (default true)
|
||||
--in-app-update Toggle ability to update via dashboard
|
||||
--statistics-retention int Days to keep statistics (default 7)
|
||||
--webserver-port int Port for the web server (default 8080)
|
||||
```
|
||||
|
||||
### Configuration File
|
||||
|
||||
Settings are stored in [settings.yaml](https://github.com/pommee/goaway/blob/main/settings.yaml). You can customize blocking rules, upstream DNS servers, and other options through the web dashboard or by editing this file directly.
|
||||
|
||||
### Examples
|
||||
|
||||
**Run on custom ports:**
|
||||
|
||||
```bash
|
||||
goaway --dns-port 6121 --webserver-port 3000
|
||||
```
|
||||
|
||||
**Disable authentication (not recommended for production):**
|
||||
|
||||
```bash
|
||||
goaway --auth=false
|
||||
```
|
||||
|
||||
**Enable debug logging:**
|
||||
|
||||
```bash
|
||||
goaway --log-level 0
|
||||
```
|
||||
|
||||
## 🔧 Development
|
||||
|
||||
### Running in Development Mode
|
||||
|
||||
The dashboard and server can be started separately for development with hot reloading:
|
||||
|
||||
```bash
|
||||
# Start the web interface (with hot reload)
|
||||
make dev-website
|
||||
|
||||
# Start the server (in another shell)
|
||||
make dev-server
|
||||
```
|
||||
|
||||
### Contributing
|
||||
|
||||
Contributions are welcomed! Here's how you can help:
|
||||
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 3.5 MiB After Width: | Height: | Size: 3.5 MiB |
7
docs/Makefile
Normal file
7
docs/Makefile
Normal file
@@ -0,0 +1,7 @@
|
||||
.PHONY: build serve
|
||||
|
||||
build:
|
||||
mkdocs build
|
||||
|
||||
serve:
|
||||
mkdocs serve
|
||||
BIN
docs/docs/assets/logo.png
Normal file
BIN
docs/docs/assets/logo.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 3.5 MiB |
BIN
docs/docs/assets/preview.png
Normal file
BIN
docs/docs/assets/preview.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 507 KiB |
|
Before Width: | Height: | Size: 56 KiB After Width: | Height: | Size: 56 KiB |
1
docs/docs/blog/index.md
Normal file
1
docs/docs/blog/index.md
Normal file
@@ -0,0 +1 @@
|
||||
Blog entries are created at times to convey certain messages. As GoAway is in the alpha stage, it will mostly explain exciting/breaking changes.
|
||||
29
docs/docs/blog/posts/1.md
Normal file
29
docs/docs/blog/posts/1.md
Normal file
@@ -0,0 +1,29 @@
|
||||
---
|
||||
date:
|
||||
created: 2025-11-08
|
||||
---
|
||||
|
||||
# The Great Rewrite
|
||||
|
||||
Since the project started 11 months ago, I have been learning Golang, React, Typescript, DNS, Vite, and much more...
|
||||
This in turn meant that major parts of the project was getting old fast, due to the poor code quality in certain areas.
|
||||
|
||||
Since the project was in dire need of improvements, I made the greatest change for GoAway thus far. [This PR](https://github.com/pommee/goaway/pull/75) refactors the majority of all backend logic and is finally in, with the hope of simplifying and speeding up future development. **So what has been done...**
|
||||
|
||||
## Services and Repositories
|
||||
|
||||
Previously, no "standard" existed in terms of how to structure logic, resulting in a very jagged flow which was hard to keep up with and often led to bugs.
|
||||
|
||||
I find that the service/repository flow is very nice, keeping business logic at the top and database/other at the lower end. Also with the addition of interfaces, testing should now be easier. Another hope is extensibility, meaning that the database can be swapped out if needed, from SQLite to PostgreSQL as an example.
|
||||
|
||||
## Documentation
|
||||
|
||||
The addition of this website. Going forward, the hope is to document any installation, configuration, workflow and such here.
|
||||
The GitHub readme is not always easy to index, so the hope is that this website can improve the experience.
|
||||
|
||||
### Minor notes
|
||||
|
||||
- Types for frontend code
|
||||
- Golang version bump (1.25.3 -> 1.25.4)
|
||||
- New project mascot
|
||||
- ~8.6k lines of code added and ~6k removed
|
||||
315
docs/docs/configuration.md
Normal file
315
docs/docs/configuration.md
Normal file
@@ -0,0 +1,315 @@
|
||||
## DNS Settings
|
||||
|
||||
### Network Configuration
|
||||
|
||||
`dns.address`
|
||||
|
||||
The IP address on which the DNS server will listen for incoming queries.
|
||||
|
||||
**Default:** `0.0.0.0` (all IPv4 addresses)
|
||||
|
||||
!!! tip "Binding Options"
|
||||
|
||||
Use `0.0.0.0` to listen on all interfaces, or specify a particular IP for more restrictive binding.
|
||||
|
||||
---
|
||||
|
||||
`dns.gateway`
|
||||
|
||||
Gateway address used when performing local lookups, primarily for finding hostnames of local clients. Will be populated if not set upon first startup.
|
||||
|
||||
**Default:** `192.168.0.1:53` (example)
|
||||
|
||||
---
|
||||
|
||||
### Performance & Caching
|
||||
|
||||
`dns.cacheTTL`
|
||||
|
||||
Maximum time (in seconds) to keep resolved domains in cache. The server uses either this value or the DNS response TTL, whichever is smaller.
|
||||
|
||||
**Default:** `360` seconds (6 minutes)
|
||||
|
||||
!!! info "Cache Behavior"
|
||||
|
||||
Lower values provide more up-to-date information but may result in fewer cached responses and increased upstream queries.
|
||||
|
||||
---
|
||||
|
||||
`dns.udpSize`
|
||||
|
||||
UDP buffer size for incoming DNS queries in bytes. This follows the standard DNS-over-UDP packet size limit per RFC 1035.
|
||||
|
||||
**Default:** `512`
|
||||
|
||||
---
|
||||
|
||||
### Ports
|
||||
|
||||
UDP / TCP
|
||||
|
||||
`dns.ports.udptcp`
|
||||
|
||||
Port for standard DNS queries. The server listens on both UDP and TCP on this port.
|
||||
|
||||
**Default:** `53`
|
||||
|
||||
---
|
||||
|
||||
DNS-over-TLS (DoT)
|
||||
|
||||
`dns.ports.dot`
|
||||
|
||||
Port for DNS-over-TLS encrypted queries.
|
||||
|
||||
**Default:** `853`
|
||||
|
||||
---
|
||||
|
||||
DNS-over-HTTPS (DoH)
|
||||
|
||||
`dns.ports.doh`
|
||||
|
||||
Port for DNS-over-HTTPS encrypted queries.
|
||||
|
||||
**Default:** `443`
|
||||
|
||||
---
|
||||
|
||||
### TLS Configuration
|
||||
|
||||
!!! warning "TLS Setup Required"
|
||||
|
||||
DoT and DoH servers will not start unless valid TLS certificates are configured.
|
||||
|
||||
`dns.tls.enabled`
|
||||
|
||||
Enable or disable TLS functionality for DoT and DoH.
|
||||
|
||||
**Default:** `false`
|
||||
|
||||
`dns.tls.cert`
|
||||
|
||||
Path to the TLS certificate file in PEM format.
|
||||
|
||||
**Default:** `""` (empty)
|
||||
|
||||
`dns.tls.key`
|
||||
|
||||
Path to the TLS private key file.
|
||||
|
||||
**Default:** `""` (empty)
|
||||
|
||||
---
|
||||
|
||||
### Upstream DNS Servers
|
||||
|
||||
`dns.upstream.preferred`
|
||||
|
||||
Primary DNS server to forward queries to.
|
||||
|
||||
**Default:** `8.8.8.8:53` (Google DNS)
|
||||
|
||||
`dns.upstream.fallback`
|
||||
|
||||
List of backup DNS servers used if the primary server fails.
|
||||
|
||||
**Default:** `[1.1.1.1:53]` (Cloudflare DNS)
|
||||
|
||||
!!! example "Multiple Fallbacks"
|
||||
|
||||
```yaml
|
||||
dns:
|
||||
upstream:
|
||||
preferred: 8.8.8.8:53
|
||||
fallback:
|
||||
- 1.1.1.1:53
|
||||
- 9.9.9.9:53
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## API & Web Interface
|
||||
|
||||
### Server Configuration
|
||||
|
||||
`api.port`
|
||||
|
||||
Port for accessing the dashboard and API endpoints.
|
||||
|
||||
**Default:** `8080`
|
||||
|
||||
!!! info "Accessing the Dashboard"
|
||||
|
||||
Navigate to `http://your-server-ip:8080` in your browser.
|
||||
|
||||
---
|
||||
|
||||
### Authentication
|
||||
|
||||
!!! warning "Production Security"
|
||||
|
||||
Always enable authentication in production environments!
|
||||
|
||||
`api.authentication`
|
||||
|
||||
Controls whether login is required to access the dashboard.
|
||||
|
||||
**Default:** `true`
|
||||
|
||||
!!! note "First Startup"
|
||||
|
||||
An admin account is created automatically on first startup. **Check the logs for the generated password.**
|
||||
|
||||
---
|
||||
|
||||
### Rate Limiting
|
||||
|
||||
`api.ratelimit.enabled`
|
||||
|
||||
Enable or disable rate limiting (currently protects only the login route).
|
||||
|
||||
**Default:** `false`
|
||||
|
||||
`api.ratelimit.maxTries`
|
||||
|
||||
Maximum number of requests before rate limiting activates.
|
||||
|
||||
**Default:** `5` attempts
|
||||
|
||||
`api.ratelimit.window`
|
||||
|
||||
Duration in minutes that rate limiting remains active after the limit is reached.
|
||||
|
||||
**Default:** `5` minutes
|
||||
|
||||
---
|
||||
|
||||
## Logging
|
||||
|
||||
`logging.enabled`
|
||||
|
||||
Master toggle for all logging functionality.
|
||||
|
||||
**Default:** `true`
|
||||
|
||||
!!! tip "Privacy & Performance"
|
||||
|
||||
Disable logging for privacy-focused deployments or to reduce disk I/O.
|
||||
|
||||
`logging.level`
|
||||
|
||||
Controls the severity of log messages displayed. Each level includes all higher-numbered levels.
|
||||
|
||||
**Default:** `1` (Info)
|
||||
|
||||
| Level | Name | Description |
|
||||
| ----- | ------- | -------------------------------------------- |
|
||||
| 0 | Debug | Most verbose, includes all messages |
|
||||
| 1 | Info | Normal operation messages |
|
||||
| 2 | Warning | Potential issues that don't affect operation |
|
||||
| 3 | Error | Serious problems only |
|
||||
|
||||
---
|
||||
|
||||
## Miscellaneous Settings
|
||||
|
||||
### Application Updates
|
||||
|
||||
`misc.inAppUpdate`
|
||||
|
||||
Enables or disables the built-in update functionality.
|
||||
|
||||
**Default:** `false`
|
||||
|
||||
!!! info "Update Behavior by Deployment Type"
|
||||
|
||||
| Deployment | Setting | Behavior |
|
||||
|------------|---------|-------------------------------------------------------------------------------------------------------|
|
||||
| Docker | `false` | Manual updates: stop container, remove, pull new image |
|
||||
| Docker | `true` | Dashboard updater fetches latest binary and restarts container automatically |
|
||||
| Standalone | `false` | Manual updates via installer or `updater.sh` |
|
||||
| Standalone | `true` | Dashboard updater installs new binary (manual restart required) |
|
||||
|
||||
---
|
||||
|
||||
### Data Retention
|
||||
|
||||
`misc.statisticsRetention`
|
||||
|
||||
Number of days to retain statistics and query logs.
|
||||
|
||||
**Default:** `7` days
|
||||
|
||||
!!! tip "Storage Optimization"
|
||||
|
||||
Lower values save disk space but provide less historical data for analysis.
|
||||
|
||||
---
|
||||
|
||||
### Dashboard Serving
|
||||
|
||||
`misc.dashboard`
|
||||
|
||||
Controls whether the web dashboard UI is served.
|
||||
|
||||
**Default:** `true`
|
||||
|
||||
!!! note "API-Only Mode"
|
||||
|
||||
When set to `false`, the API remains available but the dashboard won't be served. Useful for headless deployments.
|
||||
|
||||
---
|
||||
|
||||
### Blacklist Management
|
||||
|
||||
`misc.scheduledBlacklistUpdates`
|
||||
|
||||
Enable automatic daily updates for blacklists at midnight.
|
||||
|
||||
**Default:** `true`
|
||||
|
||||
!!! success "Recommended"
|
||||
|
||||
Keep this enabled to ensure your blacklists stay current with the latest threat intelligence.
|
||||
|
||||
---
|
||||
|
||||
## Quick Start Example
|
||||
|
||||
This is the default configuration that will be generated unless another config already exists.
|
||||
|
||||
```yaml
|
||||
dns:
|
||||
address: 0.0.0.0
|
||||
gateway: 192.168.0.1:53
|
||||
cacheTTL: 3600
|
||||
udpSize: 512
|
||||
tls:
|
||||
enabled: false
|
||||
cert: ""
|
||||
key: ""
|
||||
upstream:
|
||||
preferred: 8.8.8.8:53
|
||||
fallback:
|
||||
- 1.1.1.1:53
|
||||
ports:
|
||||
udptcp: 53
|
||||
dot: 853
|
||||
doh: 443
|
||||
api:
|
||||
port: 8080
|
||||
authentication: true
|
||||
rateLimit:
|
||||
enabled: true
|
||||
maxTries: 5
|
||||
window: 5
|
||||
logging:
|
||||
enabled: true
|
||||
level: 1
|
||||
misc:
|
||||
inAppUpdate: false
|
||||
statisticsRetention: 7
|
||||
dashboard: true
|
||||
scheduledBlacklistUpdates: true
|
||||
```
|
||||
96
docs/docs/getting-started.md
Normal file
96
docs/docs/getting-started.md
Normal file
@@ -0,0 +1,96 @@
|
||||
### Basic Usage
|
||||
|
||||
Start GoAway with default settings:
|
||||
|
||||
```shell
|
||||
$ goaway
|
||||
```
|
||||
|
||||
You'll see a startup message confirming the services are running:
|
||||
|
||||
|
||||
|
||||
!!! warning "First-time Setup"
|
||||
|
||||
GoAway runs in authenticated mode by default and generates a random password on first startup. This password is shown only once in the logs - make sure to save it!
|
||||
|
||||
### Accessing the Dashboard
|
||||
|
||||
1. Open your browser and navigate to `http://your-server-ip:port`
|
||||
2. Default username: `admin`
|
||||
3. Use the generated password from startup
|
||||
|
||||
### Configure Your Devices
|
||||
|
||||
To use GoAway as your DNS server, update your device or router settings:
|
||||
|
||||
**Router Configuration (Recommended):**
|
||||
|
||||
- Set your router's DNS server to GoAway's IP address
|
||||
- This will protect all devices on your network
|
||||
|
||||
**Individual Device:**
|
||||
|
||||
- Update DNS settings to point to GoAway's IP address
|
||||
- Primary DNS: `<goaway-server-ip>`
|
||||
- Secondary DNS: `1.1.1.1` or `8.8.8.8` - Used as a fallback
|
||||
|
||||
### Command Line Options
|
||||
|
||||
```
|
||||
goaway --help
|
||||
|
||||
Usage:
|
||||
goaway [flags]
|
||||
|
||||
Flags:
|
||||
--ansi Toggle colorized logs. Only available in non-json formatted logs (default true)
|
||||
--auth Toggle authentication for admin dashboard (default true)
|
||||
--dashboard Serve dashboard (default true)
|
||||
--dns-port int Port for the DNS server (default 53)
|
||||
--dot-port int Port for the DoT (DNS-over-TCP) server (default 853)
|
||||
--json Toggle JSON formatted logs
|
||||
--log-level int 0 = DEBUG | 1 = INFO | 2 = WARNING | 3 = ERROR (default 1)
|
||||
--logging Toggle logging (default true)
|
||||
--in-app-update Toggle ability to update via dashboard
|
||||
--statistics-retention int Days to keep statistics (default 7)
|
||||
--webserver-port int Port for the web server (default 8080)
|
||||
```
|
||||
|
||||
### Configuration File
|
||||
|
||||
Settings are stored in [settings.yaml](https://github.com/pommee/goaway/blob/main/settings.yaml). You can customize blocking rules, upstream DNS servers, and other options through the web dashboard or by editing this file directly.
|
||||
|
||||
### Examples
|
||||
|
||||
**Run on custom ports:**
|
||||
|
||||
```bash
|
||||
goaway --dns-port 6121 --webserver-port 3000
|
||||
```
|
||||
|
||||
**Disable authentication (not recommended for production):**
|
||||
|
||||
```bash
|
||||
goaway --auth=false
|
||||
```
|
||||
|
||||
**Enable debug logging:**
|
||||
|
||||
```bash
|
||||
goaway --log-level 0
|
||||
```
|
||||
|
||||
## Development
|
||||
|
||||
### Running in Development Mode
|
||||
|
||||
The dashboard and server can be started separately for development with hot reloading:
|
||||
|
||||
```bash
|
||||
# Start the web interface (with hot reload)
|
||||
make dev-website
|
||||
|
||||
# Start the server (in another shell)
|
||||
make dev-server
|
||||
```
|
||||
20
docs/docs/index.md
Normal file
20
docs/docs/index.md
Normal file
@@ -0,0 +1,20 @@
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
A lightweight DNS sinkhole for blocking unwanted domains at the network level. Block ads, trackers, and malicious domains before they reach your devices.
|
||||
|
||||
|
||||
|
||||
<a href="https://github.com/pommee/goaway/blob/improve-setup-and-structure/resources/PREVIEW.md" target="_blank">View more screenshots</a>
|
||||
|
||||
## Features
|
||||
|
||||
- DNS-level domain blocking
|
||||
- Web-based admin dashboard
|
||||
- Cross-platform / Docker support
|
||||
- Customizable blocking rules
|
||||
- Real-time statistics
|
||||
- Low resource footprint
|
||||
- And much more...
|
||||
92
docs/docs/install.md
Normal file
92
docs/docs/install.md
Normal file
@@ -0,0 +1,92 @@
|
||||
### Option 1: Docker Installation (Recommended)
|
||||
|
||||
**Quick Start:**
|
||||
|
||||
```
|
||||
docker run -d --name goaway \
|
||||
-p 53:53/udp \
|
||||
-p 53:53/tcp \
|
||||
-p 8080:8080 \
|
||||
pommee/goaway:latest
|
||||
```
|
||||
|
||||
**Using Docker Compose (Recommended for production):**
|
||||
|
||||
Data will **not persist** unless volumes are used!
|
||||
|
||||
!!! info "Hashtags are comments"
|
||||
|
||||
Remove them to make use of any setting
|
||||
|
||||
```yml
|
||||
services:
|
||||
goaway:
|
||||
image: pommee/goaway:latest
|
||||
container_name: goaway
|
||||
restart: unless-stopped
|
||||
# volumes:
|
||||
# - /path/to/config:/app/config # Custom settings.yaml configuration
|
||||
# - /path/to/data:/app/data # Database storage location
|
||||
environment:
|
||||
- DNS_PORT=${DNS_PORT:-53}
|
||||
- WEBSITE_PORT=${WEBSITE_PORT:-8080}
|
||||
# - DOT_PORT=${DOT_PORT:-853} # Port for DoT
|
||||
# - DOH_PORT=${DOH_PORT:-443} # Port for DoH
|
||||
ports:
|
||||
- "${DNS_PORT:-53}:${DNS_PORT:-53}/udp"
|
||||
- "${DNS_PORT:-53}:${DNS_PORT:-53}/tcp"
|
||||
- "${WEBSITE_PORT:-8080}:${WEBSITE_PORT:-8080}/tcp"
|
||||
# - "${DOT_PORT:-853}:${DOT_PORT:-853}/tcp"
|
||||
# - "${DOH_PORT:-443}:${DOH_PORT:-443}/tcp"
|
||||
cap_add:
|
||||
- NET_BIND_SERVICE
|
||||
- NET_RAW
|
||||
```
|
||||
|
||||
### Option 2: Quick Install
|
||||
|
||||
**Quick Install Script:**
|
||||
|
||||
```bash
|
||||
# Install latest version
|
||||
curl https://raw.githubusercontent.com/pommee/goaway/main/installer.sh | sh
|
||||
|
||||
# Install specific version
|
||||
curl https://raw.githubusercontent.com/pommee/goaway/main/installer.sh | sh /dev/stdin 0.40.4
|
||||
```
|
||||
|
||||
The installer will:
|
||||
|
||||
1. Detect your operating system and architecture
|
||||
2. Download the appropriate binary
|
||||
3. Install it to `~/.local/bin`
|
||||
4. Set up necessary permissions
|
||||
|
||||
**Manual Installation:**
|
||||
Download binaries directly from the [releases page](https://github.com/pommee/goaway/releases).
|
||||
|
||||
### Option 3: Build from Source
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone https://github.com/pommee/goaway.git
|
||||
cd goaway
|
||||
|
||||
# Build the frontend
|
||||
make build
|
||||
|
||||
# Build GoAway binary
|
||||
go build -o goaway
|
||||
|
||||
# Start the service
|
||||
./goaway
|
||||
```
|
||||
|
||||
### Option 4: Proxmox
|
||||
|
||||
If you are planning on running via Proxmox, then there is a helper-script available [here](https://community-scripts.github.io/ProxmoxVE/scripts?id=goaway), created by [Proxmox VE Helper-Scripts (Community Edition)](https://github.com/community-scripts/ProxmoxVE).
|
||||
Great alternative if you don't want to go through an as manual process and prefer not to use Docker.
|
||||
|
||||
!!! tip "Logs / Credentials"
|
||||
|
||||
Once the LXC is up and running, logs can be found in `/var/log/goaway.log`. Login credentials can be found either in the log or `~/goaway.creds`.
|
||||
54
docs/mkdocs.yml
Normal file
54
docs/mkdocs.yml
Normal file
@@ -0,0 +1,54 @@
|
||||
site_name: GoAway
|
||||
repo_name: GoAway
|
||||
repo_url: https://github.com/pommee/goaway
|
||||
|
||||
theme:
|
||||
name: material
|
||||
logo: assets/logo.png
|
||||
favicon: assets/logo.png
|
||||
|
||||
features:
|
||||
- navigation.footer
|
||||
|
||||
palette:
|
||||
- media: "(prefers-color-scheme: light)"
|
||||
scheme: default
|
||||
toggle:
|
||||
icon: material/brightness-7
|
||||
name: Switch to dark mode
|
||||
|
||||
- media: "(prefers-color-scheme: dark)"
|
||||
scheme: slate
|
||||
toggle:
|
||||
icon: material/brightness-4
|
||||
name: Switch to system preference
|
||||
|
||||
nav:
|
||||
- Home: index.md
|
||||
- Install: install.md
|
||||
- Getting Started: getting-started.md
|
||||
- Configuration: configuration.md
|
||||
- Blog:
|
||||
- blog/index.md
|
||||
- blog/posts/1.md
|
||||
|
||||
extra:
|
||||
social:
|
||||
- icon: fontawesome/brands/github
|
||||
link: https://github.com/pommee/goaway
|
||||
|
||||
plugins:
|
||||
- search:
|
||||
lang: en
|
||||
separator: '[\s\-,:!=\[\]()"/]+|(?!\b)(?=[A-Z][a-z])|\.(?!\d)|&[lg]t;'
|
||||
|
||||
- git-revision-date-localized:
|
||||
type: timeago
|
||||
|
||||
- blog:
|
||||
blog_toc: true
|
||||
|
||||
markdown_extensions:
|
||||
- admonition
|
||||
- pymdownx.details
|
||||
- pymdownx.superfences
|
||||
Reference in New Issue
Block a user