Installation

Truetask is a self-hosted project management platform distributed as a set of Docker containers. It runs entirely on your own infrastructure — no data leaves your network, no external dependencies, no internet connection required after installation. Designed for enterprise teams that need on-premises or air-gapped deployment.

The installer handles downloading, extracting, and configuring everything — you do not need to clone a repository or build from source.

Prerequisites

Requirement	Minimum	Notes
Docker	20.10+	Install Docker
Docker Compose	v2.0+	Included with Docker Desktop; Linux may need a separate install
curl	Any	Pre-installed on most systems
unzip	Any	Pre-installed on most systems
RAM	1 GB	2 GB recommended for production
Disk	2 GB	Plus storage for uploads and backups
OS	Linux, MacOS, Windows	Linux recommended for production

Install

Navigate to the directory where you want Truetask installed (e.g., /opt) and run the installer. A truetask/ subdirectory will be created in your current location.

bash <(curl -sSL https://portal.truetask.dev/install.sh)

Portal credentials required

The installer requires your Truetask Client Portal credentials (email and password). These are provided when your organization's account is created. If you don't have credentials, contact support at truetask.io.

The installer will:

1. Verify prerequisites (Docker, Docker Compose, curl, unzip)
2. Prompt for an install directory (default: ./truetask)
3. Authenticate with the Truetask Client Portal
4. Download the latest release
5. Extract files and install management scripts
6. Optionally save portal credentials for future updates

When complete, the installer creates the following directory structure:

truetask/
├── config.ini              # Version, install date, portal credentials
├── source/                 # Application code (replaced on each update)
│   ├── .env                # Configuration (generated by setup wizard)
│   ├── docker-compose.yml
│   ├── setup.sh            # Setup wizard
│   ├── db/                 # Database, hooks, frontend
│   ├── api/                # REST API
│   └── mcp/                # MCP server
├── data/                   # Persistent data (survives updates)
│   ├── .env                # Backup copy of configuration
│   ├── pb_data/            # Database and uploads
│   └── mcp_config/         # MCP configuration
├── truetask-start.sh
├── truetask-stop.sh
├── truetask-status.sh
├── truetask-update.sh
└── truetask-backup.sh

Data persistence

The source/ directory is replaced entirely during updates. Never store configuration or data inside it. The data/ directory is permanent — this is where the database, uploaded files, and backups live.

Offline / air-gapped installation

For servers in restricted networks, air-gapped environments, or environments without outbound internet access, you can install manually:

1. Download the release ZIP from the Client Portal on a machine with internet access
2. Transfer the ZIP to the target server
3. Extract to the source/ directory:

mkdir -p truetask/source
unzip truetask-vX.Y.Z.zip -d truetask/source/
chmod +x truetask/source/setup.sh

4. Run the setup wizard and start services as normal

Updates in air-gapped environments follow the same process — download the new ZIP, replace the source/ directory contents, and restart.

Configure

The installer will prompt you to run the setup wizard automatically after downloading. If you chose to skip it or need to re-run it later:

cd truetask/source
./setup.sh

The wizard walks you through each setting with validation and sensible defaults. You can also skip the wizard entirely and edit .env manually — see Manual Configuration below.

Setup wizard

The wizard configures:

Setting	Description	Required
Data directory	Where to store the database and uploads. Must be outside source/.	Yes
Workspace name	Identifies this instance (e.g., truetask-prod). Allows running multiple instances on the same server.	Yes
Public URL	The URL users will access (e.g., https://tasks.example.com). Used for email links and OAuth redirects.	Yes
Proxy port	Port exposed by the reverse proxy. Default: 80.	Yes
Admin email	Superuser email for the admin account.	Yes
Admin password	Superuser password. Must be 10+ characters with uppercase, lowercase, and a digit.	Yes
SMTP	Mail server for password resets, invitations, and notifications.	No
Push notifications	VAPID keys for browser push notifications. Auto-generated if OpenSSL is available.	No
Encryption	Encrypts sensitive settings (SMTP credentials, OAuth secrets) in the database.	No
Rate limiting	Enables API rate limiting to protect against brute-force attacks.	No

The wizard produces a .env file and saves a backup copy to the data directory.

Encryption and VAPID keys are permanent

Once the database is initialized, the encryption key and VAPID keys cannot be changed. Changing the encryption key makes encrypted settings unreadable. Changing VAPID keys breaks all existing push notification subscriptions. Choose carefully during initial setup.

Manual configuration

If you prefer not to use the wizard, copy the environment template and edit it:

cd truetask/source
cp .env.example .env
nano .env

Required variables:

Variable	Description
DATA_DIR	Path to persistent data directory (outside source/)
WORKSPACE	Docker Compose project name for this instance
PUBLIC_URL	Public URL users will access
PROXY_PORT	Port for the reverse proxy (default: 80)
POCKETBASE_ADMIN_USERNAME	Superuser email
POCKETBASE_ADMIN_PASSWORD	Superuser password

Optional variables:

Variable	Default	Description
PB_ENCRYPTION_KEY	—	32-character hex key for settings encryption
POCKETBASE_RATE_LIMIT_ENABLED	false	Enable API rate limiting
VAPID_PRIVATE_KEY	—	PEM private key for push notifications (escaped newlines)
VAPID_PUBLIC_KEY	—	URL-safe base64 public key for push notifications
VAPID_CLAIM_EMAIL	—	Contact email for VAPID claims

For SMTP configuration, see the SMTP guide.

Start

The setup wizard will offer to start the services automatically. If you skipped the wizard or need to start services manually:

cd truetask
./truetask-start.sh

The first start takes a few minutes as Docker builds the container images. Once running, open the PUBLIC_URL you configured in your browser.

Management

Management scripts are located in the Truetask root directory:

Script	Description
./truetask-start.sh	Start or restart all services
./truetask-stop.sh	Stop all services
./truetask-status.sh	Check version, container states, and disk usage
./truetask-update.sh	Check for and apply updates
./truetask-backup.sh	Create or list backups

See the Updates, Backup & Recovery, and S3 Storage guides for details.

Troubleshooting

Services fail to start

Check container logs:

cd truetask/source
docker compose logs           # All services
docker compose logs truetask-pb   # PocketBase only

Port already in use

If the proxy port is occupied, either free it or change PROXY_PORT in .env and restart.

Permission denied on data directory

PocketBase runs as UID 1000 inside the container. Ensure the data directory is writable:

sudo chown -R 1000:1000 truetask/data

Lost .env file

A backup copy is stored in the data directory. Restore it:

cp truetask/data/.env truetask/source/.env