TsFile Viewer Deployment Guide

This document describes how to deploy the TsFile Viewer application in different modes.

Table of Contents

Prerequisites

Backend Requirements

  • JDK 17 or 21 (LTS)
  • Maven 3.9+

Frontend Requirements

  • Node.js ^20.19.0 || >=22.12.0
  • pnpm package manager

Embedded Deployment

In embedded mode, the frontend static assets are bundled within the Spring Boot JAR, resulting in a single deployable artifact.

Build Steps

Linux/Mac:

chmod +x build-embedded.sh
./build-embedded.sh

Windows:

build-embedded.bat

Run the Application

java -jar backend/target/tsfile-viewer-*.jar

The application will be available at: http://localhost:8080/view/

Configuration

Edit backend/src/main/resources/application.yml:

server:
  port: 8080

tsfile:
  allowed-directories:
    - /data/tsfiles
    - /uploads/tsfiles
  upload-directory: /uploads/tsfiles

Separate Deployment

In separate mode, the frontend and backend are deployed independently, allowing for CDN hosting of static assets and horizontal scaling.

Build Steps

Linux/Mac:

chmod +x build-separate.sh
./build-separate.sh

Windows:

build-separate.bat

Frontend Deployment

Option 1: Nginx

  1. Copy frontend/dist/ to your web server directory:

    cp -r frontend/dist/* /var/www/tsfile-viewer/

  2. Configure Nginx:

    server {
    listen 80;
    server_name tsfile-viewer.example.com;

    root /var/www/tsfile-viewer;
    index index.html;

    # SPA routing fallback
    location / {
        try_files $uri $uri/ /index.html;
    }

    # Proxy API requests to backend
    location /api {
        proxy_pass http://backend-server:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # Cache static assets
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

Option 2: CDN

  1. Upload frontend/dist/ to your CDN (S3, CloudFront, etc.)

  2. Set environment variable for API base URL:

    export VITE_API_BASE_URL=https://api.example.com/api

  3. Rebuild frontend with the environment variable:

    cd frontend
pnpm build

Backend Deployment

  1. Run the Spring Boot JAR:

    java -jar backend/target/tsfile-viewer-*.jar

  2. Configure Nginx or another reverse proxy to route /api requests to the backend. This is the recommended way to connect the frontend and backend in separate deployment.

  3. For production, use systemd service:

    Create /etc/systemd/system/tsfile-viewer.service:

    [Unit]
Description=TsFile Viewer Backend
After=network.target

[Service]
Type=simple
User=tsfile
WorkingDirectory=/opt/tsfile-viewer
ExecStart=/usr/bin/java -jar /opt/tsfile-viewer/tsfile-viewer.jar
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

    Enable and start:

    sudo systemctl enable tsfile-viewer
sudo systemctl start tsfile-viewer

Configuration

Backend Configuration

Edit backend/src/main/resources/application.yml:

server:
  port: 8080
  servlet:
    context-path: /

spring:
  servlet:
    multipart:
      enabled: true
      max-file-size: 100MB
      max-request-size: 100MB
      file-size-threshold: 2MB

tsfile:
  # Whitelist of allowed directories for file browsing
  allowed-directories:
    - /data/tsfiles
    - /uploads/tsfiles

  # Directory for uploaded files
  upload-directory: /uploads/tsfiles

  # Cache configuration
  cache:
    metadata:
      max-size: 1000
      ttl-minutes: 60
    reader:
      max-size: 100
      ttl-minutes: 30

  # Query configuration
  query:
    timeout-seconds: 30
    max-result-size: 10000
    default-page-size: 100

logging:
  level:
    org.apache.tsfile.viewer: INFO
    org.apache.tsfile: WARN

Frontend Configuration

Create .env.production in frontend/:

# API base URL (for separate deployment)
VITE_API_BASE_URL=https://api.example.com/api

# For embedded deployment, leave empty or use relative path
# VITE_API_BASE_URL=/api

Production Considerations

Security

  1. Directory Whitelist: Configure tsfile.allowed-directories to restrict file system access
  2. Upload Limits: Adjust spring.servlet.multipart.max-file-size based on your needs
  3. HTTPS: Use HTTPS in production with valid SSL certificates
  4. Reverse Proxy: Use Nginx or a similar proxy for secure communication between frontend and backend

Performance

  1. JVM Options: Tune JVM heap size based on file sizes and concurrent users

    java -Xms2g -Xmx4g -jar tsfile-viewer.jar

  2. Cache Configuration: Adjust cache sizes based on available memory

    tsfile:
  cache:
    metadata:
      max-size: 2000 # Increase for more files
    reader:
      max-size: 200 # Increase for more concurrent users

  3. Frontend CDN: Use CDN for static assets to reduce server load

  4. Database: For view persistence, configure a production database instead of in-memory storage

Monitoring

  1. Spring Boot Actuator: Enable health checks and metrics

    management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics

  2. Logging: Configure log rotation and retention

    logging:
  file:
    name: /var/log/tsfile-viewer/application.log
    max-size: 10MB
    max-history: 30

Backup

  1. Uploaded Files: Regularly backup the upload-directory
  2. Configuration: Version control application.yml and environment variables
  3. Saved Views: Backup view persistence storage (if enabled)

Troubleshooting

Frontend cannot connect to backend

  • Verify reverse proxy (e.g. Nginx) configuration is correct
  • Ensure the backend is running and reachable by the proxy
  • Check VITE_API_BASE_URL - it should match your proxy entry point (default: /api)
  • Check browser console for connection errors

File upload fails

  • Check spring.servlet.multipart.max-file-size setting
  • Verify upload-directory exists and has write permissions
  • Environment overrides:
    • TSFILE_ALLOWED_DIRS: Comma-separated allowed directory list (e.g. /data/tsfiles,/uploads/tsfiles)
    • TSFILE_UPLOAD_DIR: Upload directory path (must be within allowed directories)
  • Check disk space availability

Out of memory errors

  • Increase JVM heap size with -Xmx flag
  • Reduce cache sizes in configuration
  • Check for memory leaks in long-running processes

Slow query performance

  • Reduce query.max-result-size to limit result sets
  • Increase query.timeout-seconds for large files
  • Use aggregation and downsampling for chart queries
  • Check TsFile file sizes and consider splitting large files

Support

For issues and questions, please refer to:

  • Project README.md
  • API documentation at /swagger-ui.html (if enabled)
  • GitHub issues