docs: enhance README for clarity and other docs updates for v1.4.0

* docs: enhance README for clarity

- Enhanced README.md with updated project overview, key features, quick start instructions, and detailed API usage examples.
- Improved documentation structure for better navigation and clarity, including links to relevant resources and support channels.

* docs: update resource requirements and pruning configuration in documentation

- Revised README.md to clarify resource requirements for different hardware profiles, including updated storage needs for pruning enabled and disabled scenarios.
- Enhanced documentation on pruning configuration, specifying default values and safety margins for spent UTXO pruning.
- Updated environment variable documentation to reflect changes in default settings for pruning options.

* docs: update README and Docker documentation for environment management

- Enhanced README.md to clarify log viewing instructions and added commands for merging environment files to avoid warnings.
- Updated Docker documentation to include tips for managing environment files and emphasized the deprecation of the single Docker image deployment in favor of Docker Compose for better modularity and resource management.

* docs: cleanup tags, highlight pruning info and other cosmetics

- Revised README.md to clarify that Spent UTXO pruning is enabled by default starting from v1.4.0.
- Enhanced warnings about the deprecation of the single Docker image deployment.

* docs: enhance multi-assets guide with account balance and UTXO queries

- Updated the multi-assets documentation to clarify the usage of `/account/balance` and `/account/coins` endpoints for querying account balances and UTXOs.
- Added detailed request and response examples for both endpoints, including information on querying with stake addresses and known issues.
- Improved structure with tabs for better navigation and clarity.

* docs: add offline operations deployment docs and FULL VACCUM commands after pruning to reclaim file size

* chore: update environment variable configurations

- Disabled token registry and cleared base URL in .env.docker-compose-preprod
- Updated env-vars documentation to reflect new vars and defaults

---------

Co-authored-by: Kartiiyer12 <[email protected]>

Author: linconvidal

.env.docker-compose-preprod

@@ -113,8 +113,8 @@ PEER_DISCOVERY=true
 
 ## Token Registry
 # Externally hosted token registry is currently only available for mainnet
-TOKEN_REGISTRY_ENABLED=true
-TOKEN_REGISTRY_BASE_URL=http://preview.integrations.cf-systems.internal:8080/api
+TOKEN_REGISTRY_ENABLED=false
+TOKEN_REGISTRY_BASE_URL=
 TOKEN_REGISTRY_CACHE_TTL_HOURS=1
 TOKEN_REGISTRY_LOGO_FETCH=true
 TOKEN_REGISTRY_REQUEST_TIMEOUT_SECONDS=2

README.md

@@ -22,7 +22,7 @@ When enabled, the pruning process operates as follows:
 
 1.  New UTXOs are indexed as transactions occur.
 2.  UTXOs are marked as spent when consumed in subsequent transactions.
-3.  A background job periodically permanently deletes spent UTXOs that are older than a configurable safety margin (default: 2,160 blocks, ~12 hours on mainnet). This buffer safeguards data integrity against chain rollbacks within Cardano's finality window.
+3.  A background job periodically permanently deletes spent UTXOs that are older than a configurable safety margin (default: 129,600 blocks, ~30 days on mainnet). This buffer safeguards data integrity against chain rollbacks within Cardano's finality window.
 
 **Impact Summary:**
 | Aspect | Effect |
@@ -34,7 +34,7 @@ When enabled, the pruning process operates as follows:
 
 ## Impact on Rosetta API Endpoints
 
-Spent UTXO pruning affects Rosetta API endpoints differently based on their reliance on historical transaction data. The table below summarizes the impact. Note that "Recent" refers to data within the safety margin (default ~12 hours).
+Spent UTXO pruning affects Rosetta API endpoints differently based on their reliance on historical transaction data. The table below summarizes the impact. Note that "Recent" refers to data within the safety margin (default ~30 days).
 
 :::info Oldest Block Identifier
 When pruning is enabled, the `/network/status` endpoint includes an additional `oldest_block_identifier` object in its response. This identifier corresponds to the latest fully queryable block with complete data. Below this block index, blocks might have missing data due to pruning, making historical queries unreliable.
@@ -89,24 +89,24 @@ Spent UTXO pruning is configured via environment variables, typically set in you
 # --- Spent UTXO Pruning Configuration ---
 
 # Enable or disable spent UTXO pruning.
-# Default: false (Pruning is disabled by default)
-# To enable, set to: true
+# Default: true (Pruning is enabled by default)
+# To disable, set to: false
 REMOVE_SPENT_UTXOS=true
 
 # Safety margin: Number of recent blocks for which spent UTXOs are retained.
-# Default: 2160 (approximately 12 hours of blocks on mainnet)
+# Default: 129600 (approximately 30 days of blocks on mainnet)
 # This value balances safety for rollbacks against storage savings.
-# Example: To keep ~24 hours of spent UTXOs, set to 4320.
+# Example: To keep ~7 days of spent UTXOs, set to 30240.
 # Note: Larger REMOVE_SPENT_UTXOS_LAST_BLOCKS_GRACE_COUNT values provide longer historical query support
 # but use more disk space and delay the realization of storage benefits.
-REMOVE_SPENT_UTXOS_LAST_BLOCKS_GRACE_COUNT=2160
+REMOVE_SPENT_UTXOS_LAST_BLOCKS_GRACE_COUNT=129600
 ```
 
 :::note Configuration Guidelines
 
-- Start with the default settings (`REMOVE_SPENT_UTXOS=false` keeps pruning off).
-- The provided defaults (`REMOVE_SPENT_UTXOS_LAST_BLOCKS_GRACE_COUNT=2160`) offer ~12 h of rollback safety on mainnet.
-- Increase `REMOVE_SPENT_UTXOS_LAST_BLOCKS_GRACE_COUNT` if you need a longer historical query window; decrease it for more aggressive space savings.
+- Default settings have pruning enabled (`REMOVE_SPENT_UTXOS=true`) for optimal storage efficiency.
+- The provided defaults (`REMOVE_SPENT_UTXOS_LAST_BLOCKS_GRACE_COUNT=129600`) offer ~30 days of rollback safety on mainnet.
+- Decrease `REMOVE_SPENT_UTXOS_LAST_BLOCKS_GRACE_COUNT` for more aggressive space savings (e.g., 2160 for ~12 hours); increase it if you need a longer historical query window.
   :::
 
 ## Migration and Operational Notes
@@ -132,7 +132,31 @@ The resynchronization process rebuilds the indexer database from your existing C
 
 This is necessary in two main scenarios:
 
-- **To reclaim disk space**: When you enable pruning on an existing instance, a resync will clear out historically spent UTXOs.
+- **To reclaim disk space**: When you enable pruning on an existing instance, a resync will clear out historically spent UTXOs. However, to actually reduce the file size on disk after `REMOVE_SPENT_UTXOS` is enabled and the indexer has fully synced, you must manually reclaim the space using PostgreSQL's VACUUM FULL command on the affected tables:
+
+  ```bash
+  # Connect to the PostgreSQL database
+  docker exec -e PGPASSWORD="<password>" -it <postgres-container-name> psql -U <username> -d rosetta-java
+
+  # set schema
+  set search_path to mainnet;
+
+  # Run VACUUM FULL on the tables that store UTXO data
+  VACUUM FULL tx_input;
+  VACUUM FULL address_utxo;
+  ```
+
+    :::warning Database Maintenance Required
+    The VACUUM FULL operation requires an exclusive lock on the tables and can take significant time to complete.   Plan for potential downtime during this maintenance operation. In addition, sufficient free disk space must be available, since VACUUM FULL rewrites each table by creating a new copy before replacing the old one. For example, in this case you would need approximately 400 GB of free space to complete the operation. The process will:
+
+    - **Reclaim disk space**: Remove the gaps left by deleted spent UTXOs
+    - **Reorganize table data**: Compact the remaining data for better performance
+    - **Require exclusive access**: Block all other operations on these tables during execution
+    :::
+
+    :::tip Alternative Approach
+    If you prefer to avoid the VACUUM FULL maintenance window, performing a complete indexer resynchronization (as described above) will achieve the same disk space reclamation while rebuilding the database from scratch with the new pruning configuration.
+    :::
 - **To restore full history**: When you disable pruning, a resync will rebuild the complete transaction history that was previously pruned away.
 
 :::tip Quick Resynchronization Steps

docs/docs/advanced-configuration/pruning.md

@@ -13,7 +13,7 @@ import TabItem from '@theme/TabItem';
 <Tabs>
   <TabItem value="online" label="Online Mode" default>
 
-## Online Mode
+
 
 In online mode, the system connects to the Cardano network, synchronizes the blockchain, and provides real-time access to blockchain data. This is the default mode and requires a connection to the Cardano network.
 
@@ -29,20 +29,35 @@ This mode is used for blockchain synchronization, transaction broadcasting, and
   </TabItem>
   <TabItem value="offline" label="Offline Mode">
 
-## Offline Mode
+
 
 In offline mode, the system operates without connecting to the Cardano network. The Cardano Node, YACI Indexer, and PostgreSQL components are disabled, and only the Rosetta API is active.
 
 Offline mode is useful for transaction construction and signing in air-gapped environments or security-critical applications. This mode allows you to create and sign transactions without broadcasting them to the network, which is particularly important for cold wallet solutions and high-security setups.
 
 :::tip Enabling Offline Mode
-To enable offline mode, set the `API_SPRING_PROFILES_ACTIVE` environment variable to `offline` in the configuration file:
-
+To enable offline mode, set the `API_SPRING_PROFILES_ACTIVE` and `TOKEN_REGISTRY_ENABLED` as below:
 ```bash
 API_SPRING_PROFILES_ACTIVE=offline
+TOKEN_REGISTRY_ENABLED=false
 ```
-
 :::
 
+#### Deployment Option
+
+##### Using Docker Compose
+
+1. Clone the repository
+```bash
+git clone https://github.com/cardano-foundation/cardano-rosetta-java.git
+```
+2. Use the provided environment files:
+   - The default configuration is in `.env.docker-compose`
+
+```bash
+docker compose --env-file .env.docker-compose \
+  -f docker-compose-offline.yaml up -d
+```
+
   </TabItem>
 </Tabs>

docs/docs/core-concepts/operation-modes.md

@@ -14,7 +14,7 @@ Before you begin, ensure you have the following installed:
 
 - Docker
 - Docker Compose
-- Java 21
+- Java 24
 - For integration tests: Node 14+
 
 ## Deployment Options
@@ -28,6 +28,9 @@ import TabItem from '@theme/TabItem';
 ### Using Docker Compose
 
 1. Clone the repository
+```bash
+git clone https://github.com/cardano-foundation/cardano-rosetta-java.git
+```
 2. Use the provided environment files or modify them if necessary:
    - The default configuration is in `.env.docker-compose`
    - Choose a hardware profile from the available options (see [Hardware Profiles](./hardware-profiles) for details):
@@ -44,6 +47,21 @@ docker compose --env-file .env.docker-compose \
   -f docker-compose.yaml up -d
 ```
 
+:::tip Managing Environment Files
+To avoid environment variable warnings when running `docker compose` commands later (like `docker compose logs`), you can merge the environment files:
+```bash
+# For mainnet with mid-level profile:
+cat .env.docker-compose .env.docker-compose-profile-mid-level > .env
+
+# For preprod with entry-level profile:
+cat .env.docker-compose-preprod .env.docker-compose-profile-entry-level > .env
+
+# Now you can run commands without warnings:
+docker compose ps
+docker compose logs -f
+```
+:::
+
 :::note
 The first time you run the command, it will take significant time to build the cardano-node.
 On subsequent runs, it will use the cached version.
@@ -68,9 +86,21 @@ Mithril provides cryptographically certified blockchain snapshots for multiple C
 :::
 
   </TabItem>
-  <TabItem value="prebuilt" label="Pre-built Docker Image">
+  <TabItem value="prebuilt" label="Pre-built Docker Image (Deprecated)">
+
+### Using Pre-built Docker Image (Deprecated)
 
-### Using Pre-built Docker Image
+:::danger Deprecated Feature
+⚠️ **The single Docker image deployment is deprecated and not recommended for production use.**
+
+This method bundles all components (cardano-node, indexer, API, and PostgreSQL) into a single container, which:
+- Makes resource management difficult
+- Complicates debugging and maintenance
+- Prevents independent component scaling
+- Is less reliable for production workloads
+
+**We strongly recommend using the Docker Compose deployment method instead**, which offers better modularity, resource management, and maintainability.
+:::
 
 For every release, pre-built docker images are available on [DockerHub](https://hub.docker.com/orgs/cardanofoundation/repositories):
 
@@ -100,9 +130,13 @@ API documentation is available [here](https://input-output-hk.github.io/cardano-
 :::
 
   </TabItem>
-  <TabItem value="source" label="Build from Source">
+  <TabItem value="source" label="Build from Source (Single Image)">
 
-### Building Docker Image from Source
+### Building Docker Image from Source (Single Container)
+
+:::warning Deprecated Approach
+This builds the deprecated single Docker image that bundles all components together. For production deployments, use the Docker Compose method which builds and manages components separately.
+:::
 
 ```bash
 git clone https://github.com/cardano-foundation/cardano-rosetta-java
@@ -188,21 +222,27 @@ For information about running in online mode (default) or offline mode (for air-
   <TabItem value="logs" label="Viewing Logs" default>
 
 ```bash
-# Follow Docker container logs
-docker logs rosetta -f
+# For Docker Compose deployments:
+docker compose logs -f api
+docker compose logs -f yaci-indexer
+docker compose logs -f cardano-node
 
-# Access node logs
+# For single container deployments (deprecated):
+docker logs rosetta -f
 docker exec rosetta tail -f /logs/node.log
-
-# Access indexer logs
 docker exec rosetta tail -f /logs/indexer.log
 ```
 
   </TabItem>
   <TabItem value="interactive" label="Interactive Shell">
 
 ```bash
-# Get interactive bash shell
+# For Docker Compose deployments:
+docker exec -it cardano-rosetta-java-cardano-node-1 bash
+docker exec -it cardano-rosetta-java-api-1 bash
+docker exec -it cardano-rosetta-java-yaci-indexer-1 bash
+
+# For single container deployments (deprecated):
 docker exec -it rosetta bash
 
 # Useful commands within the container