diff --git a/packages/docusaurus/docs/03-Pangolin/04-api-documentation.md b/packages/docusaurus/docs/03-Pangolin/04-api-documentation.md new file mode 100644 index 0000000..e5ce1c1 --- /dev/null +++ b/packages/docusaurus/docs/03-Pangolin/04-api-documentation.md @@ -0,0 +1,176 @@ +API documentation for pangolin. This documentation includes public endpoints, request/response formats, usage examples, and any limitations or constraints. + +## API Documentation + +### Base URL +``` +https://pangolin.yourdomain.com/v1 +``` + +### 1. Public Endpoints + +#### 1.1 User Management + +- **Create User** + - **Endpoint:** `POST /users` + - **Description:** Creates a new user account. + - **Request Format:** + ```json + { + "email": "user@example.com", + "password": "securepassword", + "name": "John Doe" + } + ``` + - **Response Format:** + ```json + { + "id": "user_id", + "email": "user@example.com", + "name": "John Doe", + "createdAt": "2025-02-18T20:51:00Z" + } + ``` + - **Usage Example:** + ```bash + curl -X POST https://pangolin.yourdomain.com/v1/users \ + -H "Content-Type: application/json" \ + -d '{"email":"user@example.com","password":"securepassword","name":"John Doe"}' + ``` + - **Limitations:** Email must be unique. + +- **Get User** + - **Endpoint:** `GET /users/{id}` + - **Description:** Retrieves user information by ID. + - **Response Format:** + ```json + { + "id": "user_id", + "email": "user@example.com", + "name": "John Doe", + "createdAt": "2025-02-18T20:51:00Z" + } + ``` + - **Usage Example:** + ```bash + curl -X GET https://pangolin.yourdomain.com/v1/users/user_id + ``` + +#### 1.2 Authentication + +- **Login User** + - **Endpoint:** `POST /auth/login` + - **Description:** Authenticates a user and returns an access token. + - **Request Format:** + ```json + { + "email": "user@example.com", + "password": "securepassword" + } + ``` + - **Response Format:** + ```json + { + "token": "access_token", + "expiresIn": 3600 + } + ``` + - **Usage Example:** + ```bash + curl -X POST https://pangolin.yourdomain.com/v1/auth/login \ + -H "Content-Type: application/json" \ + -d '{"email":"user@example.com","password":"securepassword"}' + ``` + +#### 1.3 Resource Management + +- **Create Resource** + - **Endpoint:** `POST /resources` + - **Description:** Creates a new resource. + - **Request Format:** + ```json + { + "name": "Resource Name", + "type": "HTTP", + "url": "https://example.com" + } + ``` + - **Response Format:** + ```json + { + "id": "resource_id", + "name": "Resource Name", + "type": "HTTP", + "url": "https://example.com", + "createdAt": "2025-02-18T20:51:00Z" + } + ``` + - **Usage Example:** + ```bash + curl -X POST https://pangolin.yourdomain.com/v1/resources \ + -H "Authorization: Bearer access_token" \ + -H "Content-Type: application/json" \ + -d '{"name":"Resource Name","type":"HTTP","url":"https://example.com"}' + ``` + +- **Get Resource** + - **Endpoint:** `GET /resources/{id}` + - **Description:** Retrieves resource information by ID. + - **Response Format:** + ```json + { + "id": "resource_id", + "name": "Resource Name", + "type": "HTTP", + "url": "https://example.com", + "createdAt": "2025-02-18T20:51:00Z" + } + ``` + - **Usage Example:** + ```bash + curl -X GET https://pangolin.yourdomain.com/v1/resources/resource_id \ + -H "Authorization: Bearer access_token" + ``` + +#### 1.4 Invite Management + +- **Send Invite** + - **Endpoint:** `POST /invites` + - **Description:** Sends an invite to a user. + - **Request Format:** + ```json + { + "email": "invitee@example.com" + } + ``` + - **Response Format:** + ```json + { + "inviteId": "invite_id", + "status": "sent" + } + ``` + - **Usage Example:** + ```bash + curl -X POST https://pangolin.yourdomain.com/v1/invites \ + -H 'Authorization: Bearer access_token' \ + -H 'Content-Type: application/json' \ + -d '{"email":"invitee@example.com"}' + ``` + +### 2. Request/Response Formats + +All requests should include the appropriate headers, particularly `Content-Type` set to `application/json` for JSON payloads and an `Authorization` header for authenticated requests. + +### 3. Usage Examples + +Examples of how to interact with the API are included in the endpoint descriptions above using `curl`. These examples illustrate how to make requests and handle responses. + +### 4. Limitations or Constraints + +- Each email address must be unique when creating a user. +- Resources must be associated with an organization, and users must have appropriate permissions to create or manage resources. +- Rate limits may apply to API calls (not specified in the current documentation but should be implemented to prevent abuse). +- Ensure that sensitive data (like passwords) is transmitted securely over HTTPS. + +This documentation provides a foundational overview of the API's public endpoints, request/response formats, usage examples, and any limitations. We will expand upon this as our API evolves or as additional features are added. \ No newline at end of file diff --git a/packages/docusaurus/docs/05-Gerbil/02-developer-guide.md b/packages/docusaurus/docs/05-Gerbil/02-developer-guide.md new file mode 100644 index 0000000..87958ce --- /dev/null +++ b/packages/docusaurus/docs/05-Gerbil/02-developer-guide.md @@ -0,0 +1,98 @@ +# Developer Guide for the Gerbil Project + +This guide provides essential information for developers working on the Gerbil project, which is a Go application for managing WireGuard tunnels. It includes setup instructions, an overview of the project structure, development workflow, testing approach, and common troubleshooting steps. + +## 1. Setup Instructions + +To get started with the Gerbil project, follow these setup instructions: + +### Prerequisites +- **Go**: Ensure that you have Go installed on your system. The project uses Go version 1.23.1 or later. You can download it from [golang.org](https://golang.org/dl/). +- **Docker**: Install Docker to build and run the application in a containerized environment. +- **Git**: Make sure Git is installed to clone the repository. + +### Installation Steps +1. **Clone the Repository**: + ```bash + git clone https://github.com/fosrl/gerbil.git + cd gerbil + ``` + +2. **Install Dependencies**: + Run the following command to download all required Go dependencies: + ```bash + go mod download + ``` + +3. **Build the Application**: + You can build the application using Docker or directly using Go: + - **Using Docker**: + ```bash + docker build -t gerbil . + ``` + - **Using Go**: + ```bash + go build -o gerbil main.go + ``` + +4. **Run the Application**: + To run the application, execute: + ```bash + ./gerbil \ + --reachableAt=http://gerbil:3003 \ + --generateAndSaveKeyTo=/var/config/key \ + --remoteConfig=http://pangolin:3001/api/v1/gerbil/get-config \ + --reportBandwidthTo=http://pangolin:3001/api/v1/gerbil/receive-bandwidth + ``` + +## 2. Project Structure Overview + +The project structure of Gerbil is organized as follows: + +``` +gerbil/ +├── logger/ +│ ├── level.go +│ └── logger.go +├── config_example.json +├── Dockerfile +├── entrypoint.sh +├── go.mod +├── main.go +├── Makefile +``` + +### Key Components + +- **`logger/`**: Contains logging functionality for the application. +- **`main.go`**: The entry point of the application. +- **`Dockerfile`**: Instructions for building a Docker image of the application. +- **`config_example.json`**: Example configuration file for setting up WireGuard tunnels. +- **`Makefile`**: Contains commands for building and managing the project. + +## 3. Development Workflow + +The development workflow for contributing to Gerbil involves several key steps: + +1. **Branching**: Create a new branch for your feature or bug fix. + ```bash + git checkout -b feature/my-feature-name + ``` + +2. **Coding**: Implement your changes in the codebase. + +3. **Testing Locally**: Run tests locally to ensure your changes do not break existing functionality. + +4. **Committing Changes**: Commit your changes with a descriptive message. + ```bash + git commit -m "Add feature X" + ``` + +5. **Pushing Changes**: Push your branch to the remote repository. + ```bash + git push origin feature/my-feature-name + ``` + +6. **Creating a Pull Request**: Open a pull request against the main branch of the repository. + +7. **Code Review**: Participate in code reviews and address any feedback received. \ No newline at end of file