tuitentuan/excel-tools repository overview

⁠ExcelTools API

Process Excel files through a simple HTTP API — no Excel install, no desktop automation, no client-side coding.

Upload a workbook, queue formatting and processing operations, download the result. Built on ASP.NET Core and EPPlus⁠, packaged as a single self-contained container you can run anywhere Docker runs.

⁠Why ExcelTools?

⁠Quick start

docker run -d \
  --name exceltools \
  -p 8080:8080 \
  -e Auth__ApiKeys__0="change-me-to-a-strong-secret" \
  -e EPPlus__ExcelPackage__License="NonCommercialPersonal:YourName" \
  -v exceltools-data:/app/Storages \
  YOUR_DOCKERHUB_USER/exceltools:latest

Replace YOUR_DOCKERHUB_USER/exceltools with your published image name.

Health check:

curl http://localhost:8080/health

Send every API request with:

x-api-key: change-me-to-a-strong-secret

⁠Minimal workflow

1. Upload — POST /api/Session (multipart/form-data, field file, .xlsx)
2. Process — POST /api/ExcelProcess/process with sessionId, worksheet name, and operations
3. Poll — GET /api/ExcelProcess/{processId} or GET /api/Session/{sessionId}
4. Download — GET /api/Session/{sessionId}/download when status is Completed

Example styling request:

{
  "sessionId": "<from-upload>",
  "worksheet": "Sheet1",
  "operations": [
    {
      "targetType": "Cell",
      "target": "A1:C1",
      "operationType": "Styling",
      "parameters": {
        "font": { "bold": true, "color": "#FFFFFF" },
        "fill": { "backgroundColor": "#1F4E79" },
        "alignment": { "horizontal": "Center", "vertical": "Center" }
      }
    }
  ]
}

⁠Ports & volumes

Without a volume, all sessions and files are lost when the container is removed.

⁠Environment variables

ASP.NET Core maps nested settings with __ (double underscore). Array items use __0, __1, …

⁠Required

Add more keys with Auth__ApiKeys__1, Auth__ApiKeys__2, …

Clients must send the key in header: x-api-key: <value>

⁠Strongly recommended

⁠Auth

⁠Storage & database

Persistence tip: mount a volume on /app/Storages (or set Storage__RootPath to your mount point) so the database and files survive restarts.

⁠Session lifecycle

TimeSpan formats: d.hh:mm:ss or hh:mm:ss (e.g. 12:00:00 = 12 hours, 00:30:00 = 30 minutes).

⁠Processing / workers

To replace the default extension list via env, set the indices you need, for example:

-e Processing__AllowedFileExtensions__0=".xlsx"

⁠Logging & hosting

⁠Full example (docker run)

docker run -d \
  --name exceltools \
  --restart unless-stopped \
  -p 8080:8080 \
  -e ASPNETCORE_ENVIRONMENT=Production \
  -e ASPNETCORE_HTTP_PORTS=8080 \
  -e Auth__ApiKeys__0="prod-key-alpha" \
  -e Auth__ApiKeys__1="prod-key-beta" \
  -e EPPlus__ExcelPackage__License="NonCommercialPersonal:YourName" \
  -e Storage__RootPath="/app/Storages" \
  -e Storage__MaxUploadBytes=99614720 \
  -e Session__Ttl="1.00:00:00" \
  -e Session__CleanupInterval="00:15:00" \
  -e Processing__WorkerCapacity=1 \
  -e Processing__MaxProcessingTime="00:15:00" \
  -e Processing__AllowedFileExtensions__0=".xlsx" \
  -e Logging__LogLevel__Default=Information \
  -v exceltools-data:/app/Storages \
  YOUR_DOCKERHUB_USER/exceltools:latest

⁠Docker Compose example

services:
  exceltools:
    image: YOUR_DOCKERHUB_USER/exceltools:latest
    container_name: exceltools
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      ASPNETCORE_ENVIRONMENT: Production
      ASPNETCORE_HTTP_PORTS: "8080"
      Auth__ApiKeys__0: "${EXCELTOOLS_API_KEY}"
      EPPlus__ExcelPackage__License: "${EPPLUS_LICENSE}"
      Storage__RootPath: /app/Storages
      Storage__MaxUploadBytes: "99614720"
      Session__Ttl: "1.00:00:00"
      Session__CleanupInterval: "00:15:00"
      Processing__WorkerCapacity: "1"
      Processing__MaxProcessingTime: "00:15:00"
      Processing__AllowedFileExtensions__0: ".xlsx"
      Logging__LogLevel__Default: Information
    volumes:
      - exceltools-data:/app/Storages
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 10s

volumes:
  exceltools-data:

Create a .env next to compose (do not commit secrets):

EXCELTOOLS_API_KEY=change-me-to-a-strong-secret
EPPLUS_LICENSE=NonCommercialPersonal:YourName

⁠API overview

Optional upload header: x-request-by: <caller-id>

⁠Current capabilities

• Styling operations on cells/ranges: font, fill, alignment, borders, merge, column width / auto-fit, row height
• Background job processing with status polling
• Automatic session expiry and cleanup
• SQLite-backed metadata (no external database required)

More Excel operations are planned for future image tags.

⁠Security notes

• Treat Auth__ApiKeys__* as secrets — use Docker secrets, Compose .env, or your orchestrator’s secret store
• Prefer HTTPS via a reverse proxy (Traefik, Nginx, Caddy, cloud LB) in front of port 8080
• Rotate API keys by adding a new key, updating clients, then removing the old index
• Set a correct EPPlus license for your deployment; non-commercial personal licenses are not for commercial production use

⁠Troubleshooting

⁠License

Application usage depends on your deployment terms. EPPlus requires a valid license configuration via EPPlus__ExcelPackage__License. Review EPPlus License Overview⁠ before commercial use.