OmniTools Deployment & Usage Guide

1. Prerequisites

Before deploying OmniTools, ensure you have the following installed:

For Docker deployment (recommended):

Docker Engine (version 20.10+)
Docker Compose (optional, for compose deployments)

For development/local build:

Node.js (version 18+)
npm (version 9+)
Git

Optional for development:

TypeScript knowledge (for contributing)
Familiarity with React and Material-UI

2. Installation

Docker Installation (Production)

The simplest way to run OmniTools is using Docker:

Single container:

docker run -d --name omni-tools --restart unless-stopped -p 8080:80 iib0011/omni-tools:latest

Using Docker Compose: Create a docker-compose.yml file:

services:
  omni-tools:
    image: iib0011/omni-tools:latest
    container_name: omni-tools
    restart: unless-stopped
    ports:
      - "8080:80"

Then run:

docker-compose up -d

Development Installation

For development or custom builds:

# Clone the repository
git clone https://github.com/iib0011/omni-tools.git
cd omni-tools

# Install dependencies
npm install

# Start development server
npm run dev

3. Configuration

OmniTools is designed to run with minimal configuration. All file processing happens client-side, so no server-side processing configuration is needed.

Environment Variables

The application doesn't require environment variables for basic functionality. However, for development:

NODE_ENV: Set to "development" or "production"
PORT: Development server port (default: 5173)

Localization Configuration

For translation contributions:

Visit the Locize project
Register and join the translation project
Translation files are located in public/locales/

4. Build & Run

Development Mode

npm run dev

Access the application at http://localhost:5173

Production Build

# Build the application
npm run build

# Preview production build locally
npm run preview

Testing

# Run unit tests
npm run test

# Run end-to-end tests
npm run test:e2e

Creating New Tools

To add a new tool to the application:

# Basic tool creation
npm run script:create:tool my-tool-name folder1

# Example for PDF splitter
npm run script:create:tool split pdf

# Nested directory structure
npm run script:create:tool my-tool-name folder1/folder2

# Windows syntax
npm run script:create:tool my-tool-name folder1\folder2

This command generates the necessary TypeScript files, components, and service logic for a new tool.

5. Deployment

Docker-Based Deployment

The 28MB Docker image makes OmniTools ideal for various deployment platforms:

Self-Hosted Options:

Docker Standalone: Run directly on any Linux/Windows/macOS with Docker
Docker Swarm: For clustered deployments
Kubernetes: For scalable container orchestration

Cloud Platforms:

Railway.app: One-click deployment with Docker support
Fly.io: Global edge deployment
DigitalOcean App Platform: Managed container hosting
AWS ECS/Fargate: Enterprise container hosting
Google Cloud Run: Serverless containers
Azure Container Instances: Quick container deployment

Traditional Hosting:

Build with npm run build and serve the dist folder using:
- Nginx
- Apache
- Caddy
- Any static file server

Deployment Considerations

SSL/TLS: Use a reverse proxy like Nginx or Caddy for HTTPS
Port Mapping: Map container port 80 to your desired host port
Resource Limits: The application is lightweight (28MB image)
Updates: Use watchtower or similar tools for automatic Docker image updates

Example Nginx configuration:

server {
    listen 80;
    server_name omnitools.yourdomain.com;
    
    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

6. Troubleshooting

Common Issues & Solutions

1. Docker Container Won't Start

# Check container logs
docker logs omni-tools

# Check if port is already in use
sudo lsof -i :8080

# Try running with different port
docker run -d -p 8081:80 iib0011/omni-tools:latest

2. Development Server Issues

# Clear npm cache
npm cache clean --force

# Remove node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

# Check Node.js version (requires 18+)
node --version

3. Build Failures

# Ensure TypeScript is properly installed
npm install typescript --save-dev

# Check for TypeScript errors
npx tsc --noEmit

# Clear build artifacts
rm -rf dist

4. Tool-Specific Issues

Image Processing Tools: Some tools use FFmpeg via WebAssembly; ensure your browser supports WASM
PDF Tools: Requires modern browser with PDF.js support
Video/Audio Tools: Browser must support required codecs

5. Browser Compatibility

Use Chrome 90+, Firefox 88+, Safari 14+, or Edge 90+
Enable JavaScript (required for client-side processing)
Ensure sufficient memory for large file processing

6. Getting Help

Check existing GitHub Issues
Join the Discord community
Email the maintainer: ibracool99@gmail.com

Performance Tips

Large Files: Some tools process files entirely in browser memory; limit file sizes based on available RAM
Multiple Tools: Each tool runs independently; close unused tool tabs to free memory
Browser Extensions: Disable ad-blockers if they interfere with tool functionality
Updates: Regularly update Docker image for performance improvements and bug fixes

How to Deploy & Use omni-tools