# My Charter Agent Linux Installation Guide

Version: Linux x86_64 protected package  
Target environments: customer-owned local servers, customer-owned cloud servers, and private deployments

## 1. Delivery Files

Please make sure you have received the following files:

```text
MyCharterAgent-Linux-x86_64-Protected-latest.tar.gz
MyCharterAgent-Linux-x86_64-Protected-latest.tar.gz.sha256
MyCharterAgent-Linux-Install-Guide.zh-CN.md
MyCharterAgent-Linux-Install-Guide.en-US.md
```

If a dated package is delivered, the file names may look like this:

```text
MyCharterAgent-Linux-x86_64-Protected-20260724-123159.tar.gz
MyCharterAgent-Linux-x86_64-Protected-20260724-123159.tar.gz.sha256
```

The package does not include the backend source file `app.py`. The backend has been packaged as the Linux executable file `charter_agent`.

## 2. Server Requirements

Recommended environment:

- Operating system: Ubuntu 20.04 or later; Ubuntu 22.04/24.04/26.04 is recommended
- Architecture: Linux x86_64
- CPU and memory: 2 vCPU / 4 GiB or above
- Disk: 100 GiB or above is recommended
- Network: the server must be able to access mailbox IMAP/SMTP, HiFleet API, and the configured LLM API
- Browser access: open the service port if public or LAN access is required

Notes:

- The protected package does not require the customer to install Python separately.
- The SQLite database file is created automatically. No standalone database service is required.
- If the cloud security group, firewall, or enterprise network policy blocks IMAP ports, mailbox synchronization will fail. The mailbox service ports must be allowed first.

## 3. Verify the Package

Upload the package and the `.sha256` file to the same directory on the server, then run:

```bash
sha256sum -c MyCharterAgent-Linux-x86_64-Protected-latest.tar.gz.sha256
```

Expected result:

```text
MyCharterAgent-Linux-x86_64-Protected-latest.tar.gz: OK
```

Current package SHA256:

```text
a592a615201024052e1743589395e4b1d74cb18584d286dabd4666cfdcc678b2
```

If verification fails, do not continue with installation. Request a new package.

## 4. Extract the Package

Create a dedicated directory first, then extract the package into it:

```bash
mkdir -p MyCharterAgent-Linux
tar -xzf MyCharterAgent-Linux-x86_64-Protected-latest.tar.gz -C MyCharterAgent-Linux
cd MyCharterAgent-Linux
```

The package files are extracted directly into this directory, including `install.sh`, `charter_agent`, `templates`, and the sample configuration file.

## 5. Install

Install to the default directory:

```bash
chmod +x install.sh
./install.sh
```

Default installation directory:

```text
~/.local/share/hifleet-charter-agent
```

You can also specify a custom directory:

```bash
./install.sh /opt/hifleet-charter-agent
```

The installer copies the program, templates, sample configuration, and start/stop scripts. If `config.json` already exists in the target directory, it will not be overwritten. Existing `data` directories will not be deleted.

## 6. Start the Service

Start with local-only access:

```bash
~/.local/share/hifleet-charter-agent/start_agent.sh
```

Default URL:

```text
http://127.0.0.1:8765/
```

Start with a custom port:

```bash
CHARTER_AGENT_PORT=8086 ~/.local/share/hifleet-charter-agent/start_agent.sh
```

Allow LAN or public access:

```bash
CHARTER_AGENT_HOST=0.0.0.0 CHARTER_AGENT_PORT=8086 ~/.local/share/hifleet-charter-agent/start_agent.sh
```

Browser URL:

```text
http://server-ip:8086/
```

If you use a cloud server, also open the corresponding port, such as `8086`, in the cloud security group.

## 7. First Login and User Management

When login authentication is enabled, normal users must sign in before accessing the workspace. The first startup automatically creates an administrator account.

If the administrator password was not preset in `config.json`, check the following file in the installation directory:

```text
data/initial_admin_password.txt
```

This file records the initial administrator username and password. After the first administrator sign-in, change the administrator password immediately and keep it safe.

The login page supports Simplified Chinese, Traditional Chinese, English, Japanese, Spanish, German, and Russian. On first visit it follows the browser language by default, and the selected language is saved in the browser.

Administrators can:

- Create normal users in System Settings, including username, initial password, display name, email, and role.
- Reset normal user passwords, deactivate normal users, or delete normal users that are no longer needed.
- Open the "Login Logs" view after "Subscription" on the home page to review recent sign-ins, including time, username, success/failure status, IP address, IP country/city, and browser information.

Recommendations:

- Only administrators can open System Settings. Normal users can browse, search, filter, match, and follow up records in the workspace, but cannot change system-level settings such as mailbox access, LLM, HiFleet API Key, or user management.
- Do not share one administrator account among multiple people.
- Staff should use separate normal user accounts.
- Disable or delete user accounts promptly when staff leave, credentials may have leaked, or the account is no longer needed.
- If the system is deployed on a LAN or public server, also enable HTTPS, firewall allowlists, VPN, or reverse proxy access control.

## 8. Stop the Service

```bash
~/.local/share/hifleet-charter-agent/stop_agent.sh
```

If a custom installation directory is used, run `stop_agent.sh` from that directory.

## 9. System Configuration

After the first startup, an administrator can configure the system on the web "System Settings" page, or edit the following file in the installation directory:

```text
config.json
```

Common settings include:

- Mailbox account, IMAP host, port, SSL, and mailbox password or authorization code
- Mail folders, one folder per line
- SMTP host, port, security mode, and optional SMTP password or authorization code for in-system email replies
- LLM Base URL, API Key, model name, and token limits
- Whether to allow sanitized email subjects and bodies to be sent to the LLM for parsing
- HiFleet API Key
- Whether to enable HiFleet enrichment for private tonnage/cargo records
- Language, subscription and usage, login logs, and related settings

Mailbox folders can be entered one per line or selected from the Settings page with "Fetch Folders". The system connects to the mailbox via IMAP, loads the real folder list, and writes selected folders back to the configuration. This works for both the primary mailbox and additional mailbox accounts. It is recommended when webmail folder names differ from IMAP folder names. If the password field is blank, the saved IMAP credential is used; if a new password is entered before saving, the folder fetch uses that new value for the test.

Private mailbox parsing follows the latest HiFleet mytonnages rules: mixed vessel+cargo emails extract both record types; multiple vessels or cargoes in one email are all stored; Port Line Up, berthing queues, pure news, and pure S&P messages are treated as unknown/exceptions; Laycan/OPEN extraction supports common short forms including `O/A`, `On or ABT`, `At ABT`, `ETABT`, compact ranges, and explicit dates. Vessel type is limited to six standard categories, `Geared/Gearless` is stored only as gear availability, and contact information is redacted before LLM parsing and filled back locally from the original message body.

"Display Days" has moved to the left filter panel. It controls the display window for private open vessels, private cargo, public open vessels, public cargo, matching, and search suggestions, and is saved in the current user's browser. Normal users can adjust it themselves.

On mobile or narrow screens, the page uses a compact responsive layout. Wide tonnage and cargo tables can be dragged horizontally to reveal all columns.

If service-level settings are changed, restart the service:

```bash
~/.local/share/hifleet-charter-agent/stop_agent.sh
~/.local/share/hifleet-charter-agent/start_agent.sh
```

## 10. Data and Logs

Default data directory:

```text
~/.local/share/hifleet-charter-agent/data
```

Common files:

```text
data/charter_facts.sqlite3
data/mail_archive
data/server.out.log
data/server.err.log
data/charter_agent.pid
data/initial_admin_password.txt
```

Notes:

- `charter_facts.sqlite3` is the local SQLite database.
- `mail_archive` stores archived raw `.eml` messages for in-system mail preview.
- `server.out.log` and `server.err.log` are used for troubleshooting.
- `initial_admin_password.txt` is generated only on first startup when no administrator password is preset. It is used to retrieve the initial administrator account.

## 11. Check Runtime Status

Check whether the default port is listening:

```bash
ss -ltnp | grep 8765
```

If you use port 8086:

```bash
ss -ltnp | grep 8086
```

Check service logs:

```bash
tail -n 100 ~/.local/share/hifleet-charter-agent/data/server.out.log
tail -n 100 ~/.local/share/hifleet-charter-agent/data/server.err.log
```

Check page access:

```bash
curl -I http://127.0.0.1:8765/
```

## 12. Upgrade

Before upgrading, back up configuration and data:

```bash
cp ~/.local/share/hifleet-charter-agent/config.json ~/config.json.bak
cp -r ~/.local/share/hifleet-charter-agent/data ~/charter-agent-data-bak
```

Stop the old service:

```bash
~/.local/share/hifleet-charter-agent/stop_agent.sh
```

Extract the new package and run:

```bash
chmod +x install.sh
./install.sh
```

The installer will not overwrite existing `config.json` or the `data` directory by default. Restart the service after installation:

```bash
~/.local/share/hifleet-charter-agent/start_agent.sh
```

## 13. Uninstall

Run:

```bash
~/.local/share/hifleet-charter-agent/uninstall.sh
```

The uninstall script stops the service and removes program files. Before a formal uninstall, confirm whether `config.json`, the SQLite database, and archived emails need to be backed up.

## 14. FAQ

### 14.1 The Web Page Cannot Be Opened

Check:

- Whether the service is running
- Whether the startup port is correct
- Whether the cloud security group allows the port
- Whether the Linux firewall allows the port
- Whether the service was started with `CHARTER_AGENT_HOST=0.0.0.0` when remote access is needed

### 14.2 Mailbox Synchronization Fails

Check:

- Whether the IMAP host, port, and SSL settings are correct
- Whether an app-specific password or authorization code is used, or whether the provider allows IMAP/SMTP with the mailbox login password
- If only in-system replies fail, check SMTP host, port, security mode, and SMTP password or authorization code; when SMTP is unavailable, reply in webmail while IMAP sync remains unaffected
- If the folder name is uncertain, click "Fetch Folders" in Settings and select folders from the IMAP list to avoid localized folder-name mistakes or folder-not-found errors
- Whether IMAP/SMTP is enabled for the mailbox
- Whether the server can access the mailbox IMAP port
- Whether enterprise network policies block external mailbox access

### 14.3 LLM Parsing Fails

Check:

- Whether the LLM Base URL is correct
- Whether the LLM API Key is valid
- Whether the model name is correct
- Whether sending sanitized email subjects and bodies to the LLM is allowed
- Whether the input and output token limits are sufficient

### 14.4 HiFleet Enrichment Fails

Check:

- Whether the HiFleet API Key is correct
- Whether the account has an active subscription or sufficient point balance
- Whether "HiFleet enrichment for private tonnage/cargo" is disabled
- Whether the current tonnage or cargo record contains enough information for enrichment

## 15. Security Recommendations

- Deploy on customer-owned servers or customer-owned cloud accounts.
- Do not share the same system administrator account among multiple users.
- Normal users should use separate accounts, and accounts should be disabled or deleted when staff leave or no longer need access.
- Change the administrator password after the first sign-in. If external access is enabled, combine HTTPS, firewall allowlists, VPN, or reverse proxy authentication.
- Mailbox passwords, LLM keys, and HiFleet API keys should be configured and managed by the customer.
- If the customer does not want private tonnage/cargo information sent to HiFleet, disable "HiFleet enrichment for private tonnage/cargo" in Settings.
- If the customer does not want email content sent to a public LLM, disable LLM email parsing authorization or use a customer-owned private LLM.
- If the service is exposed publicly, add a reverse proxy, access control, internal VPN, or other authentication controls.
