feat: initialize documentation structure and deployment workflow (#366)

Author: linconvidal

.github/workflows/deploy-docs.yml

@@ -0,0 +1,49 @@
+name: Deploy Docs to GitHub Pages
+
+on:
+  # Trigger on pushes to main branch
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+  # Allow manual triggering
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: write
+
+# Allow only one concurrent deployment
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    name: Deploy to GitHub Pages
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: docs
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 18
+          cache: yarn
+          cache-dependency-path: docs/yarn.lock
+
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile
+
+      - name: Build website
+        run: yarn build
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs/build
+          # User que fez o commit ao gh-pages branch
+          user_name: github-actions[bot]
+          user_email: 41898282+github-actions[bot]@users.noreply.github.com

docs/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

docs/README.md

@@ -0,0 +1,41 @@
+# Website
+
+This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
+
+### Installation
+
+```
+$ yarn
+```
+
+### Local Development
+
+```
+$ yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+### Build
+
+```
+$ yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+### Deployment
+
+Using SSH:
+
+```
+$ USE_SSH=true yarn deploy
+```
+
+Not using SSH:
+
+```
+$ GIT_USER=<Your GitHub username> yarn deploy
+```
+
+If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

docs/docs/advanced/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Advanced Configuration and Performance",
+  "position": 5,
+  "link": {
+    "type": "generated-index",
+    "description": "Advanced configuration options and performance tuning for Cardano Rosetta Java."
+  }
+} 

docs/docs/advanced/configuration-and-performance.md

@@ -0,0 +1,106 @@
+---
+sidebar_position: 1
+title: Advanced Configuration and Performance
+description: Advanced configuration options and performance tuning
+---
+
+# Advanced Configuration and Performance
+
+This guide provides details on how to tune **cardano-rosetta-java** for various workloads and resource constraints. It covers:
+
+1. [Pruning (Disk Usage Optimization)](#1-pruning-disk-usage-optimization)
+2. [Database Pool Settings (HikariCP)](#2-database-pool-settings-hikaricp)
+3. [Tomcat Thread Configuration](#3-tomcat-thread-configuration)
+4. [Example `.env` Settings](#4-example-env-settings)
+
+---
+
+## 1. Pruning (Disk Usage Optimization)
+
+Pruning removes spent (consumed) UTXOs from local storage, keeping only unspent UTXOs. This can reduce on-disk storage from ~1TB down to ~400GB, but discards historical transaction data.
+
+- Only unspent outputs are preserved.
+- You can still validate the chain’s current state (and spend tokens), since active UTXOs remain.
+- **Enable Pruning**: Set `PRUNING_ENABLED=true` in your environment (e.g., in `.env.dockerfile` or `.env.docker-compose`).
+- **Disable Pruning** (default): Set `PRUNING_ENABLED=false`.
+
+### 1.1. When to Enable Pruning
+
+- **Low Disk Environments**: If you need to minimize disk usage and only require UTXO data for current balances.
+- **Exploratory / Dev Environments**: If historical queries are not critical.
+
+### 1.2. When to Avoid Pruning
+
+- **Full Historical Data Requirements**: If you need the complete transaction history—whether for exchange operations, audit trails, or compliance mandates—do not enable pruning. Pruning discards spent UTXOs, which removes older transaction data and prevents certain types of historical lookups or reporting.
+
+---
+
+## 2. Database Pool Settings (HikariCP)
+
+cardano-rosetta-java uses [HikariCP](https://github.com/brettwooldridge/HikariCP) as the JDBC connection pool. Tuning these values can help manage concurrency and performance.
+
+| Variable                                          | Purpose                                                  | Common Defaults | Possible Tuning |
+| ------------------------------------------------- | -------------------------------------------------------- | --------------- | --------------- |
+| `SPRING_DATASOURCE_HIKARI_MAXIMUMPOOLSIZE`        | Max number of DB connections in the pool                 | 10 (example)    | 20–100          |
+| `SPRING_DATASOURCE_HIKARI_LEAKDETECTIONTHRESHOLD` | Time (ms) before a connection leak warning is logged     | 30,000          | 300,000         |
+| `SPRING_DATASOURCE_HIKARI_CONNECTIONTIMEOUT`      | Max time (ms) to wait for a free connection before error | 30,000          | 300,000         |
+
+### 2.1. Example
+
+If you’re dealing with high API request volume, consider:
+
+```bash
+SPRING_DATASOURCE_HIKARI_MAXIMUMPOOLSIZE=50
+SPRING_DATASOURCE_HIKARI_LEAKDETECTIONTHRESHOLD=300000
+SPRING_DATASOURCE_HIKARI_CONNECTIONTIMEOUT=300000
+```
+
+- This allows up to 50 connections in the pool.
+- The large leak detection threshold (5 minutes) can help in debugging slow queries.
+
+### 2.2 When to Increase Pool Size
+
+- If your logs show “connection timeout” or “pool is exhausted,” your current pool size may be insufficient.
+- Only increase `SPRING_DATASOURCE_HIKARI_MAXIMUMPOOLSIZE` if your database has the resources (CPU, RAM, I/O) to handle additional connections.
+
+---
+
+## 3. Tomcat Thread Configuration
+
+By default, Spring Boot (Tomcat) handles incoming HTTP requests with a thread pool. If you anticipate **very high** concurrency, you might adjust:
+
+- **`SERVER_TOMCAT_THREADS_MAX`**: Maximum number of threads Tomcat uses to handle requests.
+  - Start with the default (`200`).
+  - Increasing this limit can help in high-concurrency scenarios, but if your system’s bottleneck is elsewhere (e.g., database, network, or CPU), you may see limited performance gains.
+  - **Only** increase if profiling shows that Tomcat threads are maxed out and your DB can keep up.
+  - Check CPU/memory usage carefully; going too high can lead to contention and slowdowns.
+
+---
+
+## 4. Example `.env` Settings
+
+Below is a snippet of how you might configure `.env.dockerfile` or `.env.docker-compose` for higher throughput:
+
+```bash
+# --- Pruning Toggle ---
+PRUNING_ENABLED=false
+# Keep full history, requires ~1TB of disk space
+
+# --- HikariCP Database Pool ---
+SPRING_DATASOURCE_HIKARI_MAXIMUMPOOLSIZE=50
+SPRING_DATASOURCE_HIKARI_LEAKDETECTIONTHRESHOLD=300000
+SPRING_DATASOURCE_HIKARI_CONNECTIONTIMEOUT=300000
+
+# --- Tomcat Thread Pool ---
+# SERVER_TOMCAT_THREADS_MAX=200
+# Uncomment and set a higher value if needed:
+# SERVER_TOMCAT_THREADS_MAX=400
+```
+
+---
+
+## Further Reading
+
+- [Rosetta API Reference](https://docs.cdp.coinbase.com/mesh/docs/api-reference/)
+- [Yaci-Store Repository](https://github.com/bloxbean/yaci-store)
+- [Spring Boot Docs](https://docs.spring.io/spring-boot/index.html) (for more advanced server and DB config)

docs/docs/api/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Cardano Specific API Additions",
+  "position": 3,
+  "link": {
+    "type": "generated-index",
+    "description": "Documentation for Cardano-specific API extensions and features in the Rosetta implementation."
+  }
+}