Installation

Step-by-step installation guide for TMA Cloud.

Installation OptionsCopy Anchor Link

TMA Cloud can be installed in two ways:

1. Docker Compose (Recommended) - Use the project's docker-compose.yml for the easiest setup
2. Manual Installation - Build and run from source (see below)

For full Docker options (prebuilt images, build from source), see the Docker Setup Guide.

Option 1: Docker Compose (Recommended)Copy Anchor Link

No need to clone the repo. The setup script downloads docker-compose.yml and .env.example, generates the secrets, and starts the stack.

Docker-Compose PrerequisitesCopy Anchor Link

• Docker (v29.0+)
• Docker Compose (v5.0+)

StepsCopy Anchor Link

curl -fsSL https://raw.githubusercontent.com/TMA-Cloud/TMA/main/setup.sh | bash

This starts app (main API), postgres, redis, and worker (file operations, maintenance, and OnlyOffice saves) from ./tma-cloud. Access it at http://localhost:3000 or the PORT in .env.

Verify

cd tma-cloud
docker compose ps
docker compose logs -f

To set up without the script, or to change its options, see Docker Deployment.

Option 2: Manual InstallationCopy Anchor Link

Manual-Installation PrerequisitesCopy Anchor Link

• Rust (stable, from rustup) with the wasm32-unknown-unknown target
• trunk, to build the web app
• PostgreSQL (v17+)
• Redis (v6+). REDIS_URL must be set, but the server keeps running while Redis is unreachable: caching is off and live updates reach only clients of the same server process

rustup target add wasm32-unknown-unknown
cargo install trunk --locked

Installation StepsCopy Anchor Link

1. Clone RepositoryCopy Anchor Link

git clone https://github.com/TMA-Cloud/TMA.git
cd TMA

2. ConfigureCopy Anchor Link

cp .env.example .env
# Edit .env with your configuration

Required variables:

• JWT_SECRET - Secret key for JWT tokens
• FILE_ENCRYPTION_KEY - Random 32-byte key used to encrypt stored files (generate with openssl rand -base64 32)
• DATABASE_URL - Database connection, e.g. postgresql://postgres:password@localhost:5432/tma_cloud_storage
• REDIS_URL - Redis connection, e.g. redis://:password@localhost:6379/0
• PORT - Port the app listens on (default: 3000)

Optional:

• BACKEND_URL - Public backend URL (for OnlyOffice)

3. Create DatabaseCopy Anchor Link

CREATE DATABASE tma_cloud_storage;

Migrations run automatically on startup, or by hand with tma-server migrate.

4. Set Up RedisCopy Anchor Link

Linux/macOS:

# Ubuntu/Debian
sudo apt-get install redis-server

# macOS
brew install redis
brew services start redis

redis-server

Windows: Use Docker or WSL

Verify: redis-cli ping (should return PONG)

5. BuildCopy Anchor Link

# The web app, into apps/tma-cloud-web/dist
cd apps/tma-cloud-web
trunk build --release
cd ../..

# The server
cargo build --release -p tma-server

The server binary is target/release/tma-server (tma-server.exe on Windows). It finds the web app in apps/tma-cloud-web/dist; to keep the web app somewhere else, set WEB_DIST_DIR.

6. Start ApplicationCopy Anchor Link

Production:

# Terminal 1 - API and web app
./target/release/tma-server serve

# Terminal 2 - Background worker (required)
./target/release/tma-server worker

Access at http://localhost:3000

Development:

cargo run -p tma-server -- serve --with-worker

This runs the API, the web app and the worker in one process. After changing the interface, run trunk build again in apps/tma-cloud-web; the server picks up the new build without a restart.

VerificationCopy Anchor Link

1. The server logs Server listening with the port
2. Open browser: http://localhost:3000
3. Create first account (becomes admin)
4. Connect the bucket in Settings → Storage. See Storage Bucket

TroubleshootingCopy Anchor Link

Database: Verify PostgreSQL is running, and test DATABASE_URL from .env with psql "$DATABASE_URL"

Encryption key: In production the server stops if FILE_ENCRYPTION_KEY is missing, is a passphrase, or does not match the key the data was encrypted with. The log names the cause

Redis: Verify with redis-cli ping. While Redis is unreachable the app keeps working without caching, and live updates reach only clients of the same server process.

Port: Change PORT in .env if port is in use

Web app missing: A FRONTEND_NOT_BUILT error means the server did not find the web app. Run trunk build --release in apps/tma-cloud-web, or set WEB_DIST_DIR.

OnlyOffice: Configure it in Settings → Administration → Integrations (first user only). It needs BACKEND_URL.

Background Worker: Must run tma-server worker in production. See Background Workers.

Next StepsCopy Anchor Link

• Docker Deployment - Full Docker guide (prebuilt images, build from source, volumes)
• Environment Setup - Detailed environment configuration
• First Login - Create your first account