mirror of
https://github.com/andrey271192/Domain_web.git
synced 2026-09-21 14:51:57 +00:00
feat: add premium Next.js scaffold to Domain_web
Bundle geoexport-premium (Docker, docs, Next.js) alongside the working static site mirror; production VPS install still uses site/. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Андрей Бобырев
239
premium/docs/API.md
Normal file
239
premium/docs/API.md
Normal file
@@ -0,0 +1,239 @@
|
||||
# API reference
|
||||
|
||||
GeoExport exposes a **REST** API under `/api`. The contract matches [geoexport.org](https://geoexport.org) so existing clients and mirrors stay compatible.
|
||||
|
||||
**Base URL:** `https://your-instance.example.com`
|
||||
**Content-Type:** `application/json` unless noted
|
||||
**Errors:** JSON body `{ "error": "message" }` with appropriate HTTP status
|
||||
|
||||
---
|
||||
|
||||
## Catalog (cacheable)
|
||||
|
||||
### `GET /api/presets`
|
||||
|
||||
Returns preset groups with nested services and geoip/geosite category mappings.
|
||||
|
||||
**Response:** `200` — JSON array
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"group": "Мессенджеры",
|
||||
"icon": "💬",
|
||||
"slug": "messengers",
|
||||
"services": [
|
||||
{
|
||||
"name": "Telegram",
|
||||
"domain": "telegram.org",
|
||||
"keywords": ["telegram"],
|
||||
"categories": [
|
||||
{
|
||||
"full_name": "geosite:telegram",
|
||||
"name": "telegram",
|
||||
"type": "geosite",
|
||||
"source_slug": "loyalsoldier",
|
||||
"source_name": "Loyalsoldier"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `GET /api/sources`
|
||||
|
||||
Rule database sources (download URLs, compatibility).
|
||||
|
||||
**Response:** `200` — JSON array
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"slug": "loyalsoldier",
|
||||
"name": "Loyalsoldier",
|
||||
"description": "…",
|
||||
"compatible": "Xray, 3x-ui, V2Ray, Mihomo",
|
||||
"geoip_url": "https://github.com/.../geoip.dat",
|
||||
"geosite_url": "https://github.com/.../geosite.dat"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `GET /api/last-update`
|
||||
|
||||
Timestamp of the last successful geo database refresh.
|
||||
|
||||
**Response:** `200`
|
||||
|
||||
```json
|
||||
{
|
||||
"updated_at": "2026-05-24T12:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `GET /api/routing/presets`
|
||||
|
||||
Saved routing templates for the generator UI.
|
||||
|
||||
**Response:** `200` — JSON array of preset objects (structure varies by client target).
|
||||
|
||||
---
|
||||
|
||||
## Search & export
|
||||
|
||||
### `GET /api/search`
|
||||
|
||||
Search geoip/geosite categories.
|
||||
|
||||
**Query parameters**
|
||||
|
||||
| Param | Required | Description |
|
||||
|-------|----------|-------------|
|
||||
| `q` | yes | Search string |
|
||||
| `source` | no | Filter by `source_slug` |
|
||||
| `type` | no | `geoip` or `geosite` |
|
||||
|
||||
**Example**
|
||||
|
||||
```http
|
||||
GET /api/search?q=telegram&source=loyalsoldier
|
||||
```
|
||||
|
||||
**Response:** `200` — JSON array of matching categories
|
||||
|
||||
---
|
||||
|
||||
### `GET /api/export`
|
||||
|
||||
Export resolved entries as **plain text** (one category or domain per line depending on mode).
|
||||
|
||||
**Query parameters**
|
||||
|
||||
| Param | Required | Description |
|
||||
|-------|----------|-------------|
|
||||
| `category` | conditional | Full name, e.g. `geosite:telegram` |
|
||||
| `source` | no | Source slug |
|
||||
| `format` | no | Output variant (client-specific) |
|
||||
|
||||
**Response:** `200` — `text/plain`
|
||||
|
||||
**Example**
|
||||
|
||||
```bash
|
||||
curl -s 'https://your-instance/api/export?category=geosite:telegram&source=loyalsoldier' -o telegram.txt
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## DNS lookup
|
||||
|
||||
### `GET /api/lookup`
|
||||
|
||||
Resolve a domain and cross-check against loaded geo databases.
|
||||
|
||||
**Query parameters**
|
||||
|
||||
| Param | Required | Description |
|
||||
|-------|----------|-------------|
|
||||
| `domain` | yes | FQDN, e.g. `example.com` |
|
||||
|
||||
**Example**
|
||||
|
||||
```http
|
||||
GET /api/lookup?domain=anydesk.com
|
||||
```
|
||||
|
||||
**Response:** `200` — JSON with IPs, subdomains, and geodb hits (exact schema mirrors upstream).
|
||||
|
||||
---
|
||||
|
||||
## Routing generator
|
||||
|
||||
### `POST /api/routing/generate`
|
||||
|
||||
Generate a routing configuration snippet from selected rules and a template.
|
||||
|
||||
**Request body:** `application/json`
|
||||
|
||||
```json
|
||||
{
|
||||
"preset_id": "xray-default",
|
||||
"rules": ["geosite:telegram", "geoip:netflix"],
|
||||
"outbound": "proxy",
|
||||
"client": "xray"
|
||||
}
|
||||
```
|
||||
|
||||
**Response:** `200` — JSON or plain text snippet (depends on `client`)
|
||||
|
||||
**Errors:** `400` validation, `422` unsupported combination
|
||||
|
||||
---
|
||||
|
||||
## Operations
|
||||
|
||||
### `GET /api/update/status`
|
||||
|
||||
Background geo database refresh status (worker jobs).
|
||||
|
||||
**Response:** `200`
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "idle",
|
||||
"last_run": "2026-05-24T06:00:00Z",
|
||||
"progress": null
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Rate limiting (planned)
|
||||
|
||||
Public instances should enforce per-IP limits on:
|
||||
|
||||
- `/api/lookup`
|
||||
- `/api/search`
|
||||
- `/api/export`
|
||||
|
||||
Recommended defaults: **120 req/min** per IP (configurable via `GEOEXPORT_RATE_LIMIT_PER_MINUTE`).
|
||||
|
||||
---
|
||||
|
||||
## Authentication (planned)
|
||||
|
||||
Optional header:
|
||||
|
||||
```http
|
||||
Authorization: Bearer <GEOEXPORT_API_KEY>
|
||||
```
|
||||
|
||||
Required only when `GEOEXPORT_API_KEY` is set server-side.
|
||||
|
||||
---
|
||||
|
||||
## Compatibility notes
|
||||
|
||||
| Endpoint | Local JSON (mirror) | Full backend |
|
||||
|----------|---------------------|--------------|
|
||||
| `/api/presets` | Served from `data/presets.json` | PostgreSQL or static cache |
|
||||
| `/api/sources` | `data/sources.json` | Same |
|
||||
| `/api/last-update` | `data/last-update.json` | Same |
|
||||
| `/api/routing/presets` | `data/routing-presets.json` | Same |
|
||||
| `/api/search`, `/api/export`, `/api/lookup`, `/api/routing/generate` | Proxied upstream | Native handlers |
|
||||
|
||||
Mirror behavior is implemented in [Domain_web `server.mjs`](https://github.com/andrey271192/Domain_web/blob/main/site/server.mjs).
|
||||
|
||||
---
|
||||
|
||||
## GraphQL (roadmap)
|
||||
|
||||
A read-only GraphQL layer may expose `presets`, `sources`, and `search` for panel integrations. REST remains the stable contract.
|
||||
145
premium/docs/ARCHITECTURE.md
Normal file
145
premium/docs/ARCHITECTURE.md
Normal file
@@ -0,0 +1,145 @@
|
||||
# Architecture
|
||||
|
||||
GeoExport is a full-stack web application for browsing geoip/geosite rule catalogs, exporting plain-text lists, and generating client routing snippets. This document describes the **target** architecture for `geoexport-premium` and how it relates to the existing static mirror.
|
||||
|
||||
## Goals
|
||||
|
||||
1. **Self-hosted** — operators run their own instance; no mandatory third-party backend.
|
||||
2. **API-first** — every UI action has a REST equivalent for scripts and panels.
|
||||
3. **Fast catalog UX** — presets and sources are served from cache/DB, not parsed on each page view.
|
||||
4. **Heavy work off the hot path** — `.dat` ingestion and DNS resolution run in workers or upstream services.
|
||||
|
||||
## System context
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
subgraph clients [Clients]
|
||||
Browser[Web UI]
|
||||
CLI[Scripts / panels]
|
||||
end
|
||||
|
||||
subgraph geoexport [GeoExport]
|
||||
Next[Next.js App Router]
|
||||
API[REST /api]
|
||||
Worker[Geo workers]
|
||||
end
|
||||
|
||||
subgraph data [Data plane]
|
||||
PG[(PostgreSQL)]
|
||||
RD[(Redis)]
|
||||
GH[GitHub rule releases]
|
||||
end
|
||||
|
||||
Browser --> Next
|
||||
CLI --> API
|
||||
Next --> API
|
||||
API --> PG
|
||||
API --> RD
|
||||
Worker --> PG
|
||||
Worker --> GH
|
||||
API --> Worker
|
||||
```
|
||||
|
||||
## Layers
|
||||
|
||||
### Presentation (`src/app`, `src/components`)
|
||||
|
||||
- **Next.js App Router** — server components for catalog pages; client components for search, export, DNS lookup, routing builder.
|
||||
- **Tailwind CSS 4** + **shadcn/ui** — design system aligned with Linear/Vercel density.
|
||||
- **Framer Motion** — transitions for panels, modals, and theme toggle.
|
||||
|
||||
### API (`src/app/api` — planned)
|
||||
|
||||
Route handlers mirror the public contract documented in [API.md](./API.md):
|
||||
|
||||
| Concern | Implementation |
|
||||
|---------|----------------|
|
||||
| Catalog | Read presets/sources from PostgreSQL or baked JSON during bootstrap |
|
||||
| Search | Redis-backed index or PostgreSQL full-text |
|
||||
| Export | Stream plain text from resolved category lists |
|
||||
| Lookup | DNS resolver + geodb membership check |
|
||||
| Routing | Template engine for Xray / Mihomo / Sing-box snippets |
|
||||
|
||||
During migration, some routes may **proxy** to `GEOEXPORT_UPSTREAM` (default `https://geoexport.org`), matching behavior in [Domain_web](https://github.com/andrey271192/Domain_web) `server.mjs`.
|
||||
|
||||
### Data (`prisma/` — planned)
|
||||
|
||||
| Model area | Purpose |
|
||||
|------------|---------|
|
||||
| `Source` | Rule repo metadata (slug, URLs, compatibility) |
|
||||
| `PresetGroup` / `Service` | Curated UI presets |
|
||||
| `Category` | geoip:/geosite: entries per source |
|
||||
| `RoutingPreset` | Saved routing templates |
|
||||
| `UpdateJob` | Refresh status for `.dat` pulls |
|
||||
|
||||
### Cache (`redis`)
|
||||
|
||||
- Catalog responses (`presets`, `sources`, `last-update`)
|
||||
- Search result pages
|
||||
- Rate limiting counters for public API
|
||||
|
||||
### Workers (planned)
|
||||
|
||||
Background jobs:
|
||||
|
||||
1. Download `geoip.dat` / `geosite.dat` from configured GitHub releases.
|
||||
2. Parse and upsert category index into PostgreSQL.
|
||||
3. Expose progress via `GET /api/update/status`.
|
||||
|
||||
## Deployment topologies
|
||||
|
||||
### A — Single VPS (Docker Compose)
|
||||
|
||||
`web` + `postgres` + `redis` on one host. nginx terminates TLS and proxies to port 3000.
|
||||
|
||||
### B — Split managed
|
||||
|
||||
- Next.js on Vercel / Cloudflare Pages
|
||||
- Neon / RDS for PostgreSQL
|
||||
- Upstash for Redis
|
||||
|
||||
### C — Mirror-only (legacy)
|
||||
|
||||
[Domain_web](https://github.com/andrey271192/Domain_web): static SPA + Node proxy on port 4173. No PostgreSQL. Suitable until the Next.js port is feature-complete.
|
||||
|
||||
## Repository layout (target)
|
||||
|
||||
```
|
||||
geoexport-premium/
|
||||
├── src/
|
||||
│ ├── app/ # routes, layouts, API handlers
|
||||
│ ├── components/ # UI primitives (shadcn)
|
||||
│ └── lib/ # db, redis, geo parsers
|
||||
├── prisma/
|
||||
│ └── schema.prisma
|
||||
├── public/
|
||||
├── docs/
|
||||
├── docker-compose.yml
|
||||
├── Dockerfile
|
||||
└── .env.example
|
||||
```
|
||||
|
||||
## Compatibility matrix
|
||||
|
||||
| Client | Import format | Notes |
|
||||
|--------|---------------|-------|
|
||||
| Xray | geoip.dat, geosite.dat, routing rules | Primary target |
|
||||
| 3x-ui | Same as Xray | Panel import |
|
||||
| V2Ray | `.dat` lists | v2fly source |
|
||||
| Mihomo | YAML routing | Generator output |
|
||||
| Sing-box | JSON / rule-set | Generator output |
|
||||
|
||||
## Security boundaries
|
||||
|
||||
- Public read APIs are unauthenticated by default; operators should place GeoExport behind VPN or enable API keys (roadmap).
|
||||
- DNS lookup must be rate-limited to prevent abuse as an open resolver.
|
||||
- Upstream proxy mode forwards only whitelisted `/api/*` paths — never arbitrary SSRF targets.
|
||||
|
||||
## Evolution from Domain_web
|
||||
|
||||
| Domain_web | geoexport-premium |
|
||||
|------------|-------------------|
|
||||
| Static `index.html` + `server.mjs` | Next.js SSR/ISR |
|
||||
| JSON files in `data/` | PostgreSQL + optional JSON seed |
|
||||
| Proxied dynamic API | Native handlers + workers |
|
||||
| systemd + nginx install script | Docker Compose + generic reverse proxy |
|
||||
72
premium/docs/CONTRIBUTING.md
Normal file
72
premium/docs/CONTRIBUTING.md
Normal file
@@ -0,0 +1,72 @@
|
||||
# Contributing to GeoExport
|
||||
|
||||
Thanks for helping improve GeoExport. This project aims for production-grade quality — clear PRs, tested behavior, and docs that match the code.
|
||||
|
||||
## Ways to contribute
|
||||
|
||||
- Report bugs and gaps in [GitHub Issues](https://github.com/andrey271192/geoexport/issues)
|
||||
- Improve docs (README, `docs/`, API examples)
|
||||
- Port UI features from [Domain_web](https://github.com/andrey271192/Domain_web) into Next.js
|
||||
- Implement API routes and Prisma models
|
||||
- Add tests for parsers, export formatters, and routing generator
|
||||
|
||||
## Development setup
|
||||
|
||||
```bash
|
||||
git clone https://github.com/andrey271192/geoexport.git
|
||||
cd geoexport
|
||||
cp .env.example .env
|
||||
npm install
|
||||
npm run dev
|
||||
```
|
||||
|
||||
Open http://localhost:3000
|
||||
|
||||
### With Docker data services only
|
||||
|
||||
```bash
|
||||
docker compose up -d postgres redis
|
||||
# Run app on host:
|
||||
npm run dev
|
||||
```
|
||||
|
||||
## Branching
|
||||
|
||||
- `main` — stable, deployable
|
||||
- `feat/*` — features
|
||||
- `fix/*` — bug fixes
|
||||
- `docs/*` — documentation only
|
||||
|
||||
## Pull request checklist
|
||||
|
||||
- [ ] `npm run lint` passes
|
||||
- [ ] `npm run build` succeeds
|
||||
- [ ] User-facing changes documented in README or `docs/`
|
||||
- [ ] No secrets, `.env`, or large binary blobs committed
|
||||
- [ ] PR description explains **why**, not only **what**
|
||||
|
||||
## Code style
|
||||
|
||||
- **TypeScript** strict mode
|
||||
- **React** — functional components, hooks
|
||||
- **Tailwind** — utility-first; use shadcn patterns for forms/dialogs
|
||||
- **API routes** — validate input, return consistent JSON errors
|
||||
- Keep diffs focused; avoid drive-by refactors
|
||||
|
||||
## Commit messages
|
||||
|
||||
Use [Conventional Commits](https://www.conventionalcommits.org/):
|
||||
|
||||
```
|
||||
feat(api): add lookup rate limiter
|
||||
fix(export): handle empty category
|
||||
docs: update Docker deployment steps
|
||||
```
|
||||
|
||||
## Security
|
||||
|
||||
Do not open public issues for vulnerabilities. See [SECURITY.md](./SECURITY.md).
|
||||
|
||||
## License
|
||||
|
||||
By contributing, you agree that your contributions are licensed under the [MIT License](../LICENSE).
|
||||
195
premium/docs/DEPLOYMENT.md
Normal file
195
premium/docs/DEPLOYMENT.md
Normal file
@@ -0,0 +1,195 @@
|
||||
# Deployment
|
||||
|
||||
This guide covers deploying **GeoExport** (`geoexport-premium`) on a VPS or container platform. For the **static mirror** that is production-ready today, use [andrey271192/Domain_web](https://github.com/andrey271192/Domain_web).
|
||||
|
||||
## Prerequisites
|
||||
|
||||
| Resource | Minimum | Recommended |
|
||||
|----------|---------|-------------|
|
||||
| CPU | 1 vCPU | 2 vCPU |
|
||||
| RAM | 1 GB | 2 GB+ |
|
||||
| Disk | 10 GB | 20 GB+ (geo databases grow) |
|
||||
| OS | Linux (Debian/Ubuntu/Alpine) | Ubuntu 22.04 LTS |
|
||||
|
||||
Software:
|
||||
|
||||
- Docker 24+ and Docker Compose v2, **or**
|
||||
- Node.js 20+ with PostgreSQL 16 and Redis 7
|
||||
|
||||
---
|
||||
|
||||
## Option 1 — Docker Compose (recommended)
|
||||
|
||||
### 1. Clone and configure
|
||||
|
||||
```bash
|
||||
git clone https://github.com/andrey271192/geoexport.git geoexport
|
||||
cd geoexport
|
||||
cp .env.example .env
|
||||
# Edit DATABASE_URL / secrets if not using compose defaults
|
||||
```
|
||||
|
||||
### 2. Start stack
|
||||
|
||||
```bash
|
||||
docker compose up -d --build
|
||||
```
|
||||
|
||||
Services:
|
||||
|
||||
| Name | Image | Host port |
|
||||
|------|-------|-----------|
|
||||
| `web` | Built from `Dockerfile` | `3000` |
|
||||
| `postgres` | `postgres:16-alpine` | `5432` |
|
||||
| `redis` | `redis:7-alpine` | `6379` |
|
||||
|
||||
Verify:
|
||||
|
||||
```bash
|
||||
curl -f http://localhost:3000
|
||||
docker compose logs -f web
|
||||
```
|
||||
|
||||
### 3. Reverse proxy (nginx)
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 80;
|
||||
server_name geo.example.com;
|
||||
|
||||
location / {
|
||||
proxy_pass http://127.0.0.1:3000;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Add TLS with Certbot or Caddy. Set `NEXT_PUBLIC_APP_URL=https://geo.example.com` in `.env` and restart `web`.
|
||||
|
||||
---
|
||||
|
||||
## Option 2 — Bare Node.js
|
||||
|
||||
```bash
|
||||
git clone https://github.com/andrey271192/geoexport.git geoexport
|
||||
cd geoexport
|
||||
cp .env.example .env
|
||||
# Point DATABASE_URL and REDIS_URL to your instances
|
||||
|
||||
npm install
|
||||
npm run build
|
||||
NODE_ENV=production npm run start
|
||||
```
|
||||
|
||||
Use **pm2** or **systemd** for process supervision:
|
||||
|
||||
```ini
|
||||
# /etc/systemd/system/geoexport.service
|
||||
[Unit]
|
||||
Description=GeoExport Next.js
|
||||
After=network.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=geoexport
|
||||
WorkingDirectory=/opt/geoexport
|
||||
EnvironmentFile=/opt/geoexport/.env
|
||||
ExecStart=/usr/bin/npm run start
|
||||
Restart=on-failure
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Option 3 — Domain_web mirror (available now)
|
||||
|
||||
One-line install on a fresh VPS:
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/andrey271192/Domain_web/main/install.sh | sudo bash
|
||||
```
|
||||
|
||||
- Site files: `/opt/domain_web/site/`
|
||||
- Node service: `geoexport-site` on `127.0.0.1:4173`
|
||||
- nginx on port 80
|
||||
|
||||
Update cached JSON:
|
||||
|
||||
```bash
|
||||
cd /opt/domain_web/site
|
||||
curl -fsSL https://geoexport.org/api/presets -o data/presets.json
|
||||
curl -fsSL https://geoexport.org/api/sources -o data/sources.json
|
||||
curl -fsSL https://geoexport.org/api/last-update -o data/last-update.json
|
||||
curl -fsSL https://geoexport.org/api/routing/presets -o data/routing-presets.json
|
||||
sudo systemctl restart geoexport-site
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Environment variables
|
||||
|
||||
See [.env.example](../.env.example). Critical production values:
|
||||
|
||||
| Variable | Notes |
|
||||
|----------|-------|
|
||||
| `NEXT_PUBLIC_APP_URL` | Canonical public URL |
|
||||
| `DATABASE_URL` | Required when Prisma is enabled |
|
||||
| `REDIS_URL` | Required for cache/rate limits |
|
||||
| `GEOEXPORT_UPSTREAM` | Set only for hybrid/mirror mode |
|
||||
|
||||
---
|
||||
|
||||
## Database migrations (roadmap)
|
||||
|
||||
When Prisma lands in this repo:
|
||||
|
||||
```bash
|
||||
npx prisma migrate deploy
|
||||
npx prisma db seed
|
||||
```
|
||||
|
||||
Until then, Docker Postgres is provisioned but unused by the app.
|
||||
|
||||
---
|
||||
|
||||
## Updates
|
||||
|
||||
**Docker:**
|
||||
|
||||
```bash
|
||||
git pull
|
||||
docker compose up -d --build
|
||||
```
|
||||
|
||||
**Domain_web:**
|
||||
|
||||
```bash
|
||||
cd /opt/domain_web && sudo git pull && sudo systemctl restart geoexport-site
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Health checks
|
||||
|
||||
| Check | Command |
|
||||
|-------|---------|
|
||||
| HTTP | `curl -sf http://localhost:3000` |
|
||||
| Postgres | `docker compose exec postgres pg_isready -U geoexport` |
|
||||
| Redis | `docker compose exec redis redis-cli ping` |
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Symptom | Likely cause | Fix |
|
||||
|---------|--------------|-----|
|
||||
| Export/search 502 | Upstream unreachable | Check `GEOEXPORT_UPSTREAM`, outbound HTTPS |
|
||||
| Empty presets | DB not seeded | Use cached JSON or run seed (roadmap) |
|
||||
| Docker build fails | Missing lockfile | `npm install` locally, commit `package-lock.json` |
|
||||
| Port 3000 in use | Conflict | Set `PORT=3001` in `.env` and compose |
|
||||
214
premium/docs/MARKETING.md
Normal file
214
premium/docs/MARKETING.md
Normal file
@@ -0,0 +1,214 @@
|
||||
# Marketing & launch copy
|
||||
|
||||
Repository: **GeoExport** (`geoexport`) — open-source geoip/geosite export platform.
|
||||
English README: [../README.md](../README.md). Russian snippets below where noted.
|
||||
|
||||
---
|
||||
|
||||
## GitHub short description (≤350 chars)
|
||||
|
||||
```
|
||||
Self-hosted geoip/geosite export & routing platform for Xray, 3x-ui, V2Ray, Mihomo, Sing-box. 59 service presets, DNS lookup, routing generator, REST API. Next.js, PostgreSQL, Redis, Docker. Privacy-friendly alternative to hosted geo list tools.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## GitHub About section
|
||||
|
||||
**Website:** `https://github.com/andrey271192/geoexport` (or your docs URL when live)
|
||||
|
||||
**Description:** (same as short description above)
|
||||
|
||||
**Topics:** see [Topics list](#github-topics-15-20)
|
||||
|
||||
---
|
||||
|
||||
## GitHub Topics (15–20)
|
||||
|
||||
```
|
||||
geoip
|
||||
geosite
|
||||
v2ray
|
||||
xray
|
||||
sing-box
|
||||
mihomo
|
||||
3x-ui
|
||||
vpn
|
||||
routing
|
||||
proxy
|
||||
self-hosted
|
||||
nextjs
|
||||
typescript
|
||||
docker
|
||||
postgresql
|
||||
open-source
|
||||
privacy
|
||||
networking
|
||||
devtools
|
||||
russia-vpn
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Repository structure tree
|
||||
|
||||
```
|
||||
geoexport/
|
||||
├── src/
|
||||
│ ├── app/ # Next.js App Router (pages + API)
|
||||
│ │ ├── layout.tsx
|
||||
│ │ ├── page.tsx
|
||||
│ │ └── api/ # REST handlers (planned)
|
||||
│ ├── components/ # UI (shadcn/ui) — planned
|
||||
│ └── lib/ # db, redis, geo utils — planned
|
||||
├── prisma/ # schema & migrations — planned
|
||||
├── public/ # static assets
|
||||
├── docs/
|
||||
│ ├── ARCHITECTURE.md
|
||||
│ ├── API.md
|
||||
│ ├── DEPLOYMENT.md
|
||||
│ ├── CONTRIBUTING.md
|
||||
│ ├── SECURITY.md
|
||||
│ └── MARKETING.md # this file
|
||||
├── docker-compose.yml
|
||||
├── Dockerfile
|
||||
├── .env.example
|
||||
├── LICENSE
|
||||
├── package.json
|
||||
└── README.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## SEO meta description (~155 chars)
|
||||
|
||||
```
|
||||
GeoExport — self-hosted geoip & geosite lists for Xray, V2Ray, Mihomo. Export .txt, DNS lookup, routing rules. Open source, Docker, REST API.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Product Hunt tagline & blurb
|
||||
|
||||
**Tagline:** Self-hosted geo lists for your VPN stack
|
||||
|
||||
**Description:**
|
||||
|
||||
GeoExport helps you browse, search, and export geoip/geosite categories from Loyalsoldier, RuNet Freedom, v2fly, and b4geoip — without relying on a closed SaaS.
|
||||
|
||||
- 59 service presets across 9 groups
|
||||
- DNS lookup with geodb cross-check
|
||||
- Routing snippet generator for Xray / Mihomo / Sing-box
|
||||
- REST API + Docker deploy
|
||||
|
||||
Open source. Run it on your VPS in minutes.
|
||||
|
||||
---
|
||||
|
||||
## Telegram post (RU)
|
||||
|
||||
```
|
||||
🌍 GeoExport — open-source замена geoexport.org на своём сервере
|
||||
|
||||
Экспорт geoip/geosite для Xray, 3x-ui, V2Ray, Mihomo, Sing-box:
|
||||
• 9 групп пресетов, 59 сервисов
|
||||
• поиск по категориям
|
||||
• DNS lookup + проверка в базах
|
||||
• генератор routing-правил
|
||||
• экспорт .txt
|
||||
• REST API + Docker
|
||||
|
||||
Стек: Next.js, PostgreSQL, Redis.
|
||||
Код: github.com/andrey271192/geoexport
|
||||
|
||||
Звезда на GitHub = поддержка проекта ⭐
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Twitter / X launch
|
||||
|
||||
```
|
||||
We shipped GeoExport — self-hosted geoip/geosite export for Xray, V2Ray, Mihomo, Sing-box.
|
||||
|
||||
59 presets · DNS lookup · routing generator · REST API · Docker
|
||||
|
||||
Open source. Your VPS. Your data.
|
||||
|
||||
⭐ github.com/andrey271192/geoexport
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Hacker News — Show HN
|
||||
|
||||
**Title:** Show HN: GeoExport – self-hosted geoip/geosite export for Xray/V2Ray/Mihomo
|
||||
|
||||
**Body:**
|
||||
|
||||
I built GeoExport, an open-source platform to browse and export geoip/geosite rule lists used by VPN clients (Xray, 3x-ui, V2Ray, Mihomo, Sing-box).
|
||||
|
||||
It indexes categories from Loyalsoldier, RuNet Freedom, v2fly, and DanielLavrushin b4geoip, with 59 curated service presets (Telegram, YouTube, Steam, RU-blocked lists, etc.).
|
||||
|
||||
Features:
|
||||
- Search and export plain-text lists
|
||||
- DNS lookup with geodb cross-check
|
||||
- Routing config generator
|
||||
- REST API
|
||||
- Docker Compose deploy (Next.js + Postgres + Redis)
|
||||
|
||||
Motivation: operators often depend on hosted geo tools with no self-host path. GeoExport is API-first and designed to run on a cheap VPS.
|
||||
|
||||
Repo: https://github.com/andrey271192/geoexport
|
||||
|
||||
A static mirror installer already exists (Domain_web); this repo is the full Next.js rewrite.
|
||||
|
||||
Feedback on API shape and self-hosted geo DB ingestion is especially welcome.
|
||||
|
||||
---
|
||||
|
||||
## Dev.to post outline
|
||||
|
||||
**Title:** Self-hosting geoip/geosite lists with GeoExport
|
||||
|
||||
1. **Problem** — VPN panels need fresh geoip/geosite data; hosted tools are convenient but opaque.
|
||||
2. **What GeoExport does** — catalog UI, export, lookup, routing generator.
|
||||
3. **Architecture sketch** — Next.js, Postgres, Redis, workers (diagram from ARCHITECTURE.md).
|
||||
4. **Quick start** — `docker compose up`, open localhost:3000.
|
||||
5. **API examples** — `curl` for presets, search, export.
|
||||
6. **Comparison** — mirror mode (Domain_web) vs full stack.
|
||||
7. **Roadmap** — Prisma, native workers, API keys.
|
||||
8. **CTA** — star the repo, contribute via CONTRIBUTING.md.
|
||||
|
||||
Tags: `#opensource` `#vpn` `#nextjs` `#docker` `#devtools`
|
||||
|
||||
---
|
||||
|
||||
## Suggested repo naming
|
||||
|
||||
| Use case | Name |
|
||||
|----------|------|
|
||||
| Product | **GeoExport** |
|
||||
| Premium fork folder | `geoexport-premium` |
|
||||
| GitHub repo (recommended) | `geoexport` |
|
||||
| Legacy mirror | `Domain_web` (keep for install scripts) |
|
||||
|
||||
Rename path when publishing:
|
||||
|
||||
```bash
|
||||
# Example: push premium tree to new repo
|
||||
git remote add origin git@github.com:andrey271192/geoexport.git
|
||||
git push -u origin main
|
||||
```
|
||||
|
||||
Or continue on `andrey271192/Domain_web` by merging `geoexport-premium` into `site/` when the Next port is ready.
|
||||
|
||||
---
|
||||
|
||||
## One-line pitch (EN)
|
||||
|
||||
**GeoExport:** run your own geoip/geosite export API and UI for Xray-class clients — open source, Docker-ready.
|
||||
|
||||
## One-line pitch (RU)
|
||||
|
||||
**GeoExport:** свой сервер для экспорта geoip/geosite и routing-правил под Xray и Mihomo — open source, Docker.
|
||||
69
premium/docs/SECURITY.md
Normal file
69
premium/docs/SECURITY.md
Normal file
@@ -0,0 +1,69 @@
|
||||
# Security policy
|
||||
|
||||
## Supported versions
|
||||
|
||||
| Version | Supported |
|
||||
|---------|-----------|
|
||||
| `main` (latest) | Yes |
|
||||
| Older tags | Best effort |
|
||||
|
||||
## Reporting a vulnerability
|
||||
|
||||
**Please do not** file public GitHub issues for security problems.
|
||||
|
||||
1. Email or DM the maintainer with a description and reproduction steps.
|
||||
2. Allow up to **90 days** for a fix before public disclosure.
|
||||
3. We will acknowledge receipt within **72 hours** when possible.
|
||||
|
||||
Include:
|
||||
|
||||
- Affected endpoints or components
|
||||
- Impact (data leak, SSRF, RCE, etc.)
|
||||
- Proof of concept if available
|
||||
- Suggested fix (optional)
|
||||
|
||||
## Threat model (self-hosted)
|
||||
|
||||
GeoExport is typically deployed on a private VPS or internal network. Common risks:
|
||||
|
||||
| Risk | Mitigation |
|
||||
|------|------------|
|
||||
| Open DNS lookup abuse | Rate-limit `/api/lookup`; block private IP ranges in resolver |
|
||||
| SSRF via upstream proxy | Whitelist paths; fixed `GEOEXPORT_UPSTREAM` host only |
|
||||
| API scraping / DoS | Redis rate limits; nginx `limit_req` |
|
||||
| Leaked `.env` | Never commit secrets; rotate DB passwords on deploy |
|
||||
| Outdated geo databases | Monitor `/api/last-update`; automate refresh jobs |
|
||||
|
||||
## Hardening checklist (production)
|
||||
|
||||
- [ ] HTTPS only (TLS 1.2+)
|
||||
- [ ] `NEXT_PUBLIC_APP_URL` matches real hostname
|
||||
- [ ] Strong PostgreSQL password (not compose defaults)
|
||||
- [ ] Redis bound to localhost or private network
|
||||
- [ ] Firewall: expose only 80/443
|
||||
- [ ] Disable directory listing on nginx
|
||||
- [ ] Keep Node.js and base images patched (`docker compose pull`)
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Run `npm audit` before releases
|
||||
- Pin Docker image digests in production compose overrides
|
||||
- Subscribe to GitHub security advisories for this repo
|
||||
|
||||
## Data privacy
|
||||
|
||||
GeoExport processes **domains and IPs** users submit for lookup. Operators should:
|
||||
|
||||
- Document retention (if logging lookups)
|
||||
- Avoid shipping lookup logs to third parties without consent
|
||||
- Prefer self-hosted rule databases over permanent upstream proxy when feasible
|
||||
|
||||
## Safe defaults
|
||||
|
||||
- No default API keys in repository
|
||||
- Example compose passwords are for **local dev only** — change before internet exposure
|
||||
- CSP headers on Next.js responses (planned)
|
||||
|
||||
## Recognition
|
||||
|
||||
We credit reporters in release notes when they agree to be named.
|
||||
Reference in New Issue
Block a user