docs: update README with Quick Start instructions and Docker setup
rabbitprincess committed
Nov 8, 2025 at 10:31 UTC
41d9612282ca2d7e6647375488e27b7d8141a120
2 files changed
+67
-53
README.md
+22
-11
@@ -4,7 +4,7 @@
4
<img src="/portal.jpg" alt="Portal logo" width="540" />
5
</p>
6
7
-Portal is an open hosting network that transforms your local project into a public web endpoint. [See more](https://gosuda.org/portal/)
7
+Portal is an open hosting network that transforms your local project into a public web endpoint. [See more.](https://gosuda.org/portal/)
8
9
## Table of Contents
10
@@ -23,23 +23,34 @@ This enables developers to publish local services globally without managing serv
23
24
## Features
25
26
-- 🔐 **End-to-End Encryption**: Client-to-client communication is fully encrypted
27
-- 🔑 **Cryptographic Identity**: Ed25519-based identity system with verifiable signatures
28
-- 🔄 **Connection Relay**: Secure connection forwarding through central server
29
-- ⏰ **Lease Management**: Time-based lease system with automatic cleanup
30
-- 🌐 **Protocol Support**: Application-Layer Protocol Negotiation (ALPN)
26
+- 🔄 **Connection Relay**: Connects clients behind NAT or firewalls through the Portal network.
27
+- 🔐 **End-to-End Encryption**: Fully encrypted client-to-client communication, including browser sessions via a WASM-based Service Worker proxy.
28
- 🚀 **High Performance**: Multiplexed connections using yamux
32
-- 🐳 **Docker Support**: Containerized deployment ready
33
-- 🌍 **Browser E2EE Proxy**: WASM-based Service Worker for automatic browser encryption
34
-- 📱 **Multi-Platform**: Go SDK for servers, WASM SDK for browsers
29
+- ⚙️ **Simple Setting**: Build and bootstrap apps quickly using the Portal SDK or Tunnel client.
30
+- 🤖 **AI Friendly**: Instantly publish AI-generated websites or applications.
31
32
## Quick Start
33
+You can run **Portal** to host relay services, or run **App** to publish your own application through portal.
34
35
### Portal Hosting
39
-You can publish Portal for relay apps.
36
+Run Portal with Docker Compose.
37
+
38
+1. Copy env file
39
+ - `cp .env.example .env`
40
+2. Start services
41
+ - `docker compose up`
42
+3. Open in browser
43
+ - `http://localhost:4017`
44
+4. Domain setup (optional)
45
+ - Point DNS to this server:
46
+ - `A` record for `portal.example.com` → server IP
47
+ - `A` (wildcard) for `*.example.com` (or `*.portal.example.com`) → server IP
48
+ - Edit `.env` for your domain:
49
+ - `PORTAL_UI_URL=https://portal.example.com`
50
+ - `POSTAL_FRONTEND_URL=https://*.example.com`
51
+ - `BOOTSTRAP_URIS=wss://portal.example.com/relay`
52
53
### App Publishing
42
-You can Pubishing own app through portal.
54
See [portal-toys](https://github.com/gosuda/portal-toys)
55
56
## Architecture
docs/development.md
+45
-42
@@ -1,42 +1,45 @@
1
-# 개발 원칙 및 운영 가이드
2
-
3
-이 문서는 Portal 프로젝트의 핵심 방향과 범위를 명확히 정의하여 불필요한 기능 추가나 방향 이탈을 방지하고, 일관된 사용자 경험을 유지하기 위한 목적을 갖습니다.
4
-
5
----
6
-
7
-## 1. 사용성 불변 원칙
8
-Portal 개발자는 자신이 구현한 기능이 기존 사용성에 변화를 주지 않도록 해야 합니다. 여기서 사용성의 변화란 다음을 모두 포함합니다.
9
-
10
-- Portal 사용 과정의 변경
11
-- Portal 배포 방식의 변경
12
-- SDK 개발 환경의 변경
13
-- 코드베이스의 복잡성 증가
14
-- 그 외
15
-
16
----
17
-
18
-## 2. 변경 시 사전 합의 절차
19
-기능 개발이 사용성에 변화를 줄 경우, 변경 전 구성원에게 문서를 통해 변경 사유를 충분히 설명하고 사전 동의를 구해야 합니다.
20
-
21
-- 기능 변경에 한해, 제안자를 제외한 1명 이상의 리뷰어 동의가 있을 때만 머지할 수 있습니다.
22
-
23
----
24
-
25
-## 3. 테스트 및 품질 보증
26
-Portal 개발자는 완성되지 않은 실험적 기능을 마스터 브랜치에 직접 반영해서는 안 됩니다. 모든 신규 기능은 개인 브랜치에서 충분한 테스트와 검증을 마친 후에만 머지할 수 있습니다.
27
-
28
----
29
-
30
-## 4. 프로젝트의 철학과 범위
31
-Portal은 개인이 로컬에서 실행하는 서비스를 세상에 공개하기 위한 중계 계층이며, End-to-End Encryption 을 제공합니다. 그 외의 목표는 현재 단계에서 다루지 않습니다.
32
-
33
-- 기능 추가를 제안할 경우 위와 마찬가지로 구성원에게 충분한 설명과 합의가 필요합니다.
34
-- 합의된 기능은 추후 로드맵에 반영하여 관리합니다.
35
-
36
----
37
-
38
-## 5. 의견 충돌 시 원칙
39
-상기 내용과 관련해 개발자 간 의견 차이가 발생할 경우,
40
-건전한 토론을 통해 합의점을 도출합니다.
41
-
42
----
\ No newline at end of file
1
+# Development Principles and Operational Guide
2
+
3
+This document defines the core principles and operational scope of the Portal project.
4
+It aims to prevent unnecessary feature expansion or direction drift, and to maintain a consistent user experience.
5
+
6
+---
7
+
8
+## 1. Usability Invariance Principle
9
+Portal developers must ensure that any new feature does not alter existing usability.
10
+A "change in usability" includes, but is not limited to:
11
+
12
+- Modifications to the Portal usage flow
13
+- Changes to the deployment or configuration process
14
+- Alterations to the SDK development environment
15
+- Increases in codebase complexity
16
+- Any similar impacts that may affect the user experience
17
+
18
+---
19
+
20
+## 2. Prior Agreement for Changes
21
+If a feature impacts usability, the proposer must provide a clear written rationale and obtain prior agreement from the team before proceeding.
22
+
23
+- A merge is permitted only when at least one reviewer (other than the proposer) approves the change.
24
+
25
+---
26
+
27
+
28
+## 3. Testing and Quality Assurance
29
+Unfinished or experimental features must not be merged directly into the main branch.
30
+All new features must be fully tested and verified in a personal branch before merging.
31
+
32
+---
33
+
34
+## 4. Project Philosophy and Scope
35
+Portal serves as a relay layer that allows individuals to publicly expose locally running services, with built-in end-to-end encryption.
36
+
37
+- When proposing new features, include sufficient justification and follow the agreement process described above.
38
+- Approved features must be documented and tracked in the project roadmap.
39
+
40
+---
41
+
42
+## 5. Principles for Resolving Disagreements
43
+If differences of opinion arise, resolve them through constructive discussion and consensus.
44
+
45
+---