Installation and Deployment

About 10 min

Installation and Deployment

This chapter covers offline installation, configuration, startup, and connection setup for TimechoAgent 0.3.0. Run the commands in Bash on the target server. Examples use /root/timecho-agent-0.3.0-linux-x86_64, the installation directory used in the documented test. Replace it with your actual directory if different. Replace <...>, /path/to/..., and example.com placeholders with actual values.

1. Pre-installation Checks

1.1 Check the Operating System and Permissions

whoami
cat /etc/os-release

Root privileges are expected.

1.2 Check That Docker Is Installed and Running

docker --version
docker info

Docker version used in the documented test:

Docker version 28.2.2

If Docker is not running:

systemctl enable --now docker

1.3 Install Docker Compose v2

The TimechoAgent 0.3.0 deployment template requires Docker Compose v2.20 or later.

Check the current version:

docker compose version

On Ubuntu 24.04, install the system package:

apt-get update
DEBIAN_FRONTEND=noninteractive apt-get install -y docker-compose-v2
docker compose version

Version used in the documented test:

Docker Compose version 2.40.3+ds1-0ubuntu1~24.04.1

Use docker compose throughout the following steps. Legacy docker-compose 1.29.x is incompatible with the current deployment template.

1.4 Check Disk Space and Ports

Check disk space:

df -h / /var/lib/docker

The documented test had approximately 45 GB free before installation, and the package was approximately 394 MB. Reserve at least 5 GB of free space.

Check whether the web port is occupied:

ss -lntp | grep -E ':8080\b'

No output means port 8080 is available.

In the documented test, nginx was already listening on port 80, so TimechoAgent used 8080 without conflict. If 8080 is occupied, change HTTP_PORT in .env.

2. Extract and Verify the Package

2.1 Upload the Package

Upload this file to /root/ on the server:

timecho-agent-0.3.0-linux-x86_64.zip

2.2 Extract

cd /root
unzip -q timecho-agent-0.3.0-linux-x86_64.zip

The extracted directory should contain:

/root/timecho-agent-0.3.0-linux-x86_64/
├── README.md
├── SHA256SUMS
├── deploy/
│   ├── .env.example
│   └── docker-compose.prod.yml
├── docs/
└── images/
    └── timecho-agent-0.3.0-images.tar.gz

2.3 Verify Package Integrity

cd /root/timecho-agent-0.3.0-linux-x86_64
sha256sum -c SHA256SUMS

All files should report OK. All checks passed in the documented test.

3. Configure the Deployment Environment

3.1 Create `.env`

cd /root/timecho-agent-0.3.0-linux-x86_64/deploy
cp .env.example .env
chmod 600 .env

If .env already exists, back it up before editing:

cp -a .env ".env.bak-$(date +%Y%m%d-%H%M%S)"

3.2 Generate and Save Random Secrets

Generate the PostgreSQL password, application encryption key, and JWT signing key:

POSTGRES_PASSWORD="$(openssl rand -hex 24)"
TIMECHO_SECRET_KEY="$(openssl rand -base64 48 | tr -d '\n')"
TIMECHO_JWT_SECRET="$(openssl rand -base64 48 | tr -d '\n')"

sed -i \
  -e "s|^POSTGRES_PASSWORD=.*|POSTGRES_PASSWORD=${POSTGRES_PASSWORD}|" \
  -e "s|^TIMECHO_SECRET_KEY=.*|TIMECHO_SECRET_KEY=${TIMECHO_SECRET_KEY}|" \
  -e "s|^TIMECHO_JWT_SECRET=.*|TIMECHO_JWT_SECRET=${TIMECHO_JWT_SECRET}|" \
  .env

Setting	Purpose
`POSTGRES_PASSWORD`	Connection password for the Agent metadata database
`TIMECHO_SECRET_KEY`	Encrypts sensitive settings such as model API keys and database passwords
`TIMECHO_JWT_SECRET`	Signs sign-in tokens

Losing TIMECHO_SECRET_KEY makes existing encrypted data impossible to decrypt. Back it up securely together with .env.

3.3 Configure the Context Name and Database Password

Edit .env:

vi .env

At minimum, check these settings:

# Listen on all network interfaces using port 8080
HTTP_BIND=0.0.0.0
HTTP_PORT=8080

# Default TimechoDB Context name; cannot be empty or 26-dev
TIMECHO_CLI_CTX=timechodb-prod

# Actual TimechoDB password; replace the placeholder, do not keep CHANGE_ME
TIMECHODB_PASSWORD='ACTUAL_DATABASE_PASSWORD'

# Time zone
TZ=Asia/Shanghai

TIMECHO_CLI_CTX is the Context name, not a database address.
TIMECHODB_PASSWORD is the password of the account used by the Context to connect to TimechoDB.
Enclose passwords containing $, #, spaces, or other special characters in single quotes.
timechodb-prod must exactly match the Context name created in Configure and Verify a TimechoDB Context.
These settings specify only the Context name and password; they do not create a database instance. TimechoDB must already be available when the pre-installation checks in Check Disk Space and Ports are completed.
An administrator must create or confirm the Context through timecho-cli in Configure and Verify a TimechoDB Context. Contexts cannot be created, modified, or deleted through natural language.

3.4 Optional: Set the Initial Administrator Password

To specify an initial administrator password, set this in .env:

TIMECHO_BOOTSTRAP_ADMIN_PASSWORD='CUSTOM_INITIAL_PASSWORD'

If left empty, the system generates a random password on first startup and writes it to:

/app/data/initial-admin-password

Keeping the default empty value and allowing random generation is recommended.

3.5 Check `.env` Permissions

chmod 600 .env
stat -c '%a %U:%G %n' .env

Expected output:

600 root:root .env

4. Load Offline Images

From the package root directory:

cd /root/timecho-agent-0.3.0-linux-x86_64
docker load -i images/timecho-agent-0.3.0-images.tar.gz

Images loaded in the documented test:

timecho-agent-backend:0.3.0
timecho-agent-frontend:0.3.0
postgres:18

Check the images:

docker image ls | grep -E 'timecho-agent|postgres'

5. Validate Compose Configuration

cd /root/timecho-agent-0.3.0-linux-x86_64/deploy
docker compose config -q

No output and exit code 0 indicate successful validation.

An error such as:

Missing mandatory value for "environment" option interpolating ...

usually indicates an empty required variable in .env. In particular, check:

grep -nE '^(TIMECHO_CLI_CTX|TIMECHODB_PASSWORD|POSTGRES_PASSWORD|TIMECHO_SECRET_KEY|TIMECHO_JWT_SECRET)=' .env

Common causes:

TIMECHO_CLI_CTX= is empty.
TIMECHODB_PASSWORD= is empty.
Legacy docker-compose is being used.
The current directory is not deploy, so Compose has not read the correct .env.

Compose usually reports only the first empty variable. After correcting it, run docker compose config -q again to check the remaining required settings.

6. Start the Services

6.1 Start

cd /root/timecho-agent-0.3.0-linux-x86_64/deploy
docker compose up -d

On first startup, the system:

Creates Docker networks and data volumes.
Starts PostgreSQL and waits for its health check.
Starts the backend, runs database migrations, and initializes the administrator.
Starts the frontend after the backend becomes healthy.

6.2 Check Status

docker compose ps

All three services should be Up and healthy:

timecho-agent-prod-postgres-1    Up ... (healthy)
timecho-agent-prod-backend-1     Up ... (healthy)
timecho-agent-prod-frontend-1    Up ... (healthy)

In the documented test, the backend became healthy after about 17 seconds, followed by the frontend.

View logs:

docker compose logs --tail=200 backend
docker compose logs --tail=100 frontend

Follow backend logs:

docker compose logs -f backend

7. Verify the Installation

7.1 Test the Local API

curl -fsS http://127.0.0.1:8080/api/v1/system/info

Key response fields from the documented test:

{
  "code": "OK",
  "data": {
    "name": "TimechoAgent",
    "version": "0.3.0",
    "demoMode": false
  }
}

7.2 Test the Server IP

curl -fsS http://<TimechoAgent_IP>:8080/api/v1/system/info

A valid JSON response indicates that the listening address and port are configured correctly.

7.3 Open in a Browser

Open:

http://<TimechoAgent_IP>:8080/

8.1 Find the Initial Administrator Password

Item	Location or value
Web URL	`http://<TimechoAgent_IP>:8080/`
Administrator username	`admin`
Default initial password file	`/app/data/initial-admin-password` inside the backend container
Custom initial password	The value of `TIMECHO_BOOTSTRAP_ADMIN_PASSWORD` in `.env`, if configured

The default password file is inside the backend container, not in deploy/.env or directly in the host's deploy directory. Run:

cd /root/timecho-agent-0.3.0-linux-x86_64/deploy
docker compose exec backend cat /app/data/initial-admin-password

If TIMECHO_BOOTSTRAP_ADMIN_PASSWORD is set in .env, no random initial password is generated. Sign in with the configured value instead.

The initial password is only for first sign-in. Do not share it through screenshots, chat tools, or public documents.

You must change the password after first sign-in. The new password must:

Contain at least eight characters.
Include at least three of uppercase letters, lowercase letters, digits, and symbols.
Differ from the username and its reverse.

Sign out and sign in again with the new password to verify it.

8.3 Remove the Initial Password File

After verifying the new password, remove the initial password file from the backend container to prevent later misuse:

docker compose exec backend rm /app/data/initial-admin-password

Verify removal:

docker compose exec backend sh -lc 'test ! -e /app/data/initial-admin-password && echo "Initial password file removed"'

8.4 Configure a Language Model (Required)

Agent conversations and natural-language database operations require a configured language model service. After first sign-in and the administrator password change, configure at least one usable model and pass its connectivity test before proceeding with database connection setup or use, or any approved data operations. Model configuration is a prerequisite for Agent features after sign-in.

Sign in to the web console as an administrator.
Open Model Configuration → Add Configuration.
Choose OpenAI-Compatible API or the integration type matching the actual service.
Enter the configuration name, Base URL, API Key, model name, and context window.
Enable Tool Calling for database operations. Enable Image Understanding if image analysis is needed.
Run Connectivity Test and save after it succeeds.
Set the model as the agent's default and confirm the setting on the Agents page.

The model service must be reachable from the TimechoAgent server, not just the computer running the browser. API keys are stored encrypted. Do not put actual keys in this guide or share them through public chat tools.

In Conversation Workbench, select the agent with the configured default model and send a general question, such as:

Reply "Model connection is working" without performing any database operations.

A valid response confirms the model integration. You can then use administrator-configured Contexts for queries and data operations, with approval for writes as prompted. Context creation, modification, deletion, and switching cannot be performed through natural language.

9. Configure and Verify a TimechoDB Context

Capability boundary: TimechoAgent cannot install TimechoDB instances or create, modify, delete, or switch TimechoDB Contexts through natural language. Administrators must configure connection addresses, accounts, passwords, dialects, and TLS on the server using timecho-cli. Agent conversations can only use Contexts that are already configured.

A TimechoDB Context is the connection configuration used to access an existing TimechoDB instance. It creates neither a database service instance nor a database account. Context lifecycle management is an administrative operations task outside natural-language conversations. CLI-based Context setup and web-based model setup are independent; both must be completed before using a database connection in Conversation Workbench.

Administrators must perform these tasks outside the Agent conversation:

Operation	Recommended entry	Description
Create Context	`timecho-cli` from the server's `deploy` directory	Configure host, port, account, dialect, TLS, and other connection settings
Modify Context	`timecho-cli ctx update`	Change only explicitly specified settings
Delete Context	`timecho-cli ctx remove`	High-risk operation; confirm the impact before proceeding
Verify Context	`timecho-cli ctx list/show` and an SQL connection test	Confirm configuration and connectivity
Use Context	Web Conversation Workbench	Use an existing connection without changing its configuration

The current version has no equivalent natural-language operation for creating or modifying a Context. This restriction is intentional. Do not attempt to bypass it through prompts.

9.1 Prepare Connection Information

Use information from an existing, accessible TimechoDB instance. The addresses and accounts below are placeholders and must be replaced for deployment.

Parameter	Example	Description
Context name	`timechodb-prod`	Must match `TIMECHO_CLI_CTX` in `.env`
Database address	`<TimechoDB_IP_OR_HOSTNAME>`	Address of the deployed TimechoDB server
Port	`6667`	Default port
Database user	`<DATABASE_USERNAME>`	An existing dedicated account, preferably with minimum required permissions
Database password	`<ACTUAL_PASSWORD>`	Corresponds to `TIMECHODB_PASSWORD` in `.env`
Dialect	`tree` or `table`	Must match the actual data model
Default database	`iotdb`	Specify as needed for `table` mode

9.2 Create a Context (Administrator CLI)

Run these commands from deploy. Choose Tree or Table according to the actual data model.

Tree model:

cd /root/timecho-agent-0.3.0-linux-x86_64/deploy

docker compose exec backend timecho-cli ctx add timechodb-prod \
  --host '<TimechoDB_IP_OR_HOSTNAME>' \
  --port 6667 \
  --user '<DATABASE_USERNAME>' \
  --dialect tree \
  --json --non-interactive

Table model:

cd /root/timecho-agent-0.3.0-linux-x86_64/deploy

docker compose exec backend timecho-cli ctx add timechodb-prod \
  --host '<TimechoDB_IP_OR_HOSTNAME>' \
  --port 6667 \
  --user '<DATABASE_USERNAME>' \
  --dialect table \
  --database iotdb \
  --json --non-interactive

Restrictions:

Do not ask the Agent to create or modify a Context in a web conversation. The current version rejects such requests under its security policy.
Do not add --password-stdin. The CLI reads the password from the backend container's TIMECHODB_PASSWORD environment variable.
Do not add -u root. The image's default user must write Context settings to the shared volume.
For the Table model, explicitly specify --dialect table and an existing default database.
For TLS, mount the CA, client certificate, and private key separately, then use the appropriate --tls, --ca, --cert, and --key options.
Do not create duplicate Context names. Inspect an existing Context before making changes.

9.3 Modify a Context (Administrator CLI)

Inspect the current configuration first:

docker compose exec backend timecho-cli ctx list --json --non-interactive
docker compose exec backend timecho-cli ctx show timechodb-prod --json --non-interactive

For example, change the database address and port:

docker compose exec backend timecho-cli ctx update timechodb-prod \
  --host '<NEW_TimechoDB_IP_OR_HOSTNAME>' \
  --port 6667 \
  --json --non-interactive

Changes to the dialect or default database must match the target database's actual data model:

docker compose exec backend timecho-cli ctx update timechodb-prod \
  --dialect table \
  --database iotdb \
  --json --non-interactive

ctx update changes only explicitly specified options. Record the original configuration with ctx show first.
Database passwords and TLS credentials are controlled configuration. Do not pass them through chat messages, command arguments, or logs.
To rotate credentials, update the controlled settings in .env first, then use the current options in timecho-cli ctx update --help to update and verify the connection.
Context deletion is high risk. Confirm that no user or agent still needs the Context before using ctx remove. Do not delete it through natural language.
After changes, notify users to verify connections again so they do not continue using old addresses or credentials.

9.4 Verify a Context

After creation or modification, run:

docker compose exec backend timecho-cli ctx list --json --non-interactive
docker compose exec backend timecho-cli ctx show timechodb-prod --json --non-interactive

Test the connection:

docker compose exec backend timecho-cli sql "SHOW DATABASES" \
  --ctx timechodb-prod \
  --json --non-interactive

A returned database list confirms that the Context connects to TimechoDB. Only then sign in to Conversation Workbench and use the Context.

9.5 Bind Users

Sign in to the web console as admin.
Open User Management.
Create or edit a user.
Select or enter timechodb-prod under Database Context.
Save.

This assigns an existing Context to a user without creating or changing its connection settings. Administrators must still use timecho-cli to modify the Context itself.

Production recommendations:

Create a dedicated database account for the Agent.
Do not use the database root account directly.
Grant minimum required permissions for the relevant business databases.
Do not allow regular users to bypass approval for high-risk writes.

10. Service Start and Stop Commands

Use this section for service control and quick inspection after installation. Routine Operations covers routine inspections, resources, and troubleshooting.

Run the following commands in deploy:

cd /opt/timecho-agent/deploy

Check running status:

docker compose ps

View backend logs:

docker compose logs --tail=200 backend

Follow logs:

docker compose logs -f backend

Restart all services:

docker compose restart

Stop services:

docker compose stop

Start again:

docker compose start

Stop and remove containers and networks while retaining data volumes:

docker compose down

Do not run docker compose down -v unless you explicitly intend to delete PostgreSQL data, Agent data, and CLI Context configuration.

11. Troubleshooting

11.1 `Missing mandatory value for "environment" option`

Cause: A required variable in .env is empty.

Check:

grep -nE '^(TIMECHO_CLI_CTX|TIMECHODB_PASSWORD|POSTGRES_PASSWORD|TIMECHO_SECRET_KEY|TIMECHO_JWT_SECRET)=' .env

Fill in missing values and run:

docker compose config -q

11.2 `docker: unknown command: compose`

Cause: Legacy docker-compose is installed, but Compose v2 is missing.

apt-get update
DEBIAN_FRONTEND=noninteractive apt-get install -y docker-compose-v2
docker compose version

11.3 Backend Fails to Start

Check logs:

docker compose logs --tail=300 backend

Common causes:

Inconsistent PostgreSQL passwords.
TIMECHO_SECRET_KEY is shorter than 32 bytes.
TIMECHO_JWT_SECRET is empty.
TIMECHO_CLI_CTX equals 26-dev.
The initial administrator password does not satisfy the security policy.
PostgreSQL is unhealthy.

11.4 Frontend Does Not Start

The frontend depends on the backend health check. Check the backend first:

docker compose ps
docker compose logs --tail=200 backend

The frontend starts automatically after the backend becomes healthy.

11.5 Signed In but Natural-Language Conversations Fail

If the web console opens but Conversation Workbench does not work, check:

A language model was configured and passed the connectivity test in Configure a Language Model (Required).
The agent has a default model.
An administrator configured and verified the Context using timecho-cli.
The model supports Tool Calling and its Base URL is reachable from the Agent server.
Execution Channels reports a normal state.
Backend logs contain no model authentication, timeout, or network errors.

cd /root/timecho-agent-0.3.0-linux-x86_64/deploy
docker compose logs --tail=200 backend

11.6 Context Connection Fails

Check:

docker compose exec backend timecho-cli ctx list --json --non-interactive
docker compose exec backend timecho-cli sql "SHOW DATABASES" --ctx timechodb-prod --json --non-interactive

Verify:

The TimechoDB address and port are reachable.
The account and TIMECHODB_PASSWORD are correct.
The tree/table dialect is correct.
The default database exists in Table mode.
The container can resolve and reach the database host.
Any database TLS allowlist or IP restrictions permit the connection.

11.7 Natural Language Cannot Create or Modify Contexts

This is expected behavior in the current version. Database instance installation and Context lifecycle management are intentionally outside TimechoAgent's natural-language capabilities.

Ask an administrator to configure the Context from the server's deploy directory with timecho-cli ctx add/update/remove.
Verify it with ctx list/show and SHOW DATABASES.
Sign in to Conversation Workbench again and use the configured Context for natural-language interaction.
Do not prompt the Agent to bypass the restriction.