Assetmanager/docs/INSTALLATION.md

# AssetManager installation guide

This guide describes a Docker image based installation and the first-start behavior of AssetManager.

## 1. Prepare the installation directory

Create a dedicated directory and the persistent data directories:

```bash
mkdir -p /srv/docker/assetmanager
cd /srv/docker/assetmanager
mkdir -p data/config data/uploads data/logs data/backups data/scripts data/postgres
```

Create a `.env` file. Use strong, unique values for all secrets:

```env
ASSETMANAGER_VERSION=0.5.5.47
APP_PORT=8088
POSTGRES_DB=assetmanager
POSTGRES_USER=assetmanager
POSTGRES_PASSWORD=CHANGE_ME
SESSION_SECRET=CHANGE_ME_LONG_RANDOM
LOCAL_ADMIN_USERNAME=emergency-admin
LOCAL_ADMIN_PASSWORD=CHANGE_ME_MIN_12_CHARS
MESHCENTRAL_PASSWORD=
LDAP_BIND_PASSWORD=
BACKUP_INTERVAL_HOURS=8
BACKUP_RETENTION_DAYS=3
```

Keep `.env` private. Do not commit it to a public repository.

## 2. Docker Compose file for a registry image

Use the published image instead of building the application locally:

```yaml
name: assetmanager

services:
  db:
    image: postgres:16-alpine
    container_name: assetmanager-db
    restart: unless-stopped
    environment:
      POSTGRES_DB: ${POSTGRES_DB:-assetmanager}
      POSTGRES_USER: ${POSTGRES_USER:-assetmanager}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-change-me}
    volumes:
      - ./data/postgres:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-assetmanager} -d ${POSTGRES_DB:-assetmanager}"]
      interval: 5s
      timeout: 5s
      retries: 10

  app:
    image: git.jusaro.de/roland/assetmanager:${ASSETMANAGER_VERSION:-0.5.5.47}
    container_name: assetmanager-app
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
    environment:
      DATABASE_URL: postgresql+psycopg://${POSTGRES_USER:-assetmanager}:${POSTGRES_PASSWORD:-change-me}@db:5432/${POSTGRES_DB:-assetmanager}
      APP_TITLE: AssetManager
      APP_CONFIG: /app/config/config.json
      APPINFO_PATH: /app/config/APPINFO.json
      BACKUP_DIR: /data/backups
      BACKUP_INTERVAL_HOURS: ${BACKUP_INTERVAL_HOURS:-8}
      BACKUP_RETENTION_DAYS: ${BACKUP_RETENTION_DAYS:-3}
      MESHCENTRAL_PASSWORD: ${MESHCENTRAL_PASSWORD:-}
      SYNC_LOG_DIR: /app/data/logs/sync
      DIAGNOSTIC_DIR: /app/data/logs/diagnostics
      LDAP_BIND_PASSWORD: ${LDAP_BIND_PASSWORD:-}
      SESSION_SECRET: ${SESSION_SECRET:-}
      LOCAL_ADMIN_USERNAME: ${LOCAL_ADMIN_USERNAME:-}
      LOCAL_ADMIN_PASSWORD: ${LOCAL_ADMIN_PASSWORD:-}
    ports:
      - "${APP_PORT:-8088}:8000"
    volumes:
      - ./data/config:/app/config
      - ./data/uploads:/app/app/static/uploads
      - ./data/logs:/app/data/logs
      - ./data/backups:/data/backups
      - ./data/scripts:/scripts
```

If the registry is private, sign in once on the Docker host:

```bash
docker login git.jusaro.de
```

## 3. First start

Pull and start the containers:

```bash
docker compose pull
docker compose up -d
docker compose ps
```

On the first start, the container creates the following files only when they do not already exist:

```text
data/config/config.json
data/config/APPINFO.json
```

Existing files are preserved during subsequent container starts and updates.

## 4. Important: authentication is initially disabled

A fresh default configuration starts with authentication disabled. This is intentional so the initial configuration can be completed, but the installation must not be exposed to an untrusted network in this state.

The web interface displays a warning banner while authentication is disabled. To enable local authentication:

1. Open `data/config/config.json`.
2. Locate the `authentication` section.
3. Set `mode` to `local`.
4. Restart only the application container:

```bash
docker compose restart app
```

5. Sign in using `LOCAL_ADMIN_USERNAME` and `LOCAL_ADMIN_PASSWORD` from `.env`.

The local administrator is the protected emergency account and should remain available even when LDAP/Active Directory is configured later.

## 5. Configure the callback base address

Remote jobs call back to AssetManager after execution. In **Software settings**, configure the callback base address when clients must reach AssetManager through DNS, a reverse proxy, VPN, or the Internet.

Examples:

```text
https://assetmanager.example.org
https://assetmanager.example.org:8443
http://192.168.1.40:8088
```

For Internet-facing use, HTTPS through a properly configured reverse proxy is strongly recommended. The callback endpoint must be reachable from the managed client.

If no callback base address is configured, AssetManager derives the address from the current request.

## 6. Verify the installation

Check the application status and logs:

```bash
docker compose ps
docker compose logs --tail=100 -f
```

After signing in, verify at least:

- application version
- database connection
- local emergency administrator login
- MeshCentral connectivity, if used
- one test inventory or remote job
- successful callback processing

## 7. Persistent data and backups

The following paths contain persistent runtime data and must survive image replacement:

```text
data/config/
data/postgres/
data/uploads/
data/logs/
data/backups/
data/scripts/
.env
```

Back up `.env` and the complete `data/` directory before significant updates.

## 8. Updating an image-based installation

Set the desired fixed image version in `.env`, for example:

```env
ASSETMANAGER_VERSION=0.5.5.47
```

Then update:

```bash
docker compose pull
docker compose down
docker compose up -d
docker compose ps
docker compose logs --tail=100 -f
```

Using a fixed version tag is recommended for controlled production updates.

## 9. Log files

Application logs are stored below `data/logs/`. The main files include `errors.log` and, when LDAP is used, `ldap.log`.

Starting with version 0.5.5.45, these file loggers detect if their active log file was deleted or replaced externally. On the next log event, the file is reopened and created again automatically; an application container restart is no longer required.

For normal log maintenance, rotation/truncation mechanisms are preferable to manually deleting active log files. Docker container output remains available through:

```bash
docker compose logs --tail=100 -f
```

## 10. Troubleshooting

### The web interface logs in as guest

The default configuration still has authentication disabled. Set `authentication.mode` to `local` in `data/config/config.json` and restart the app container.

### A remote job remains at “callback pending”

Check:

- whether the callback base address is reachable from the client
- reverse proxy/firewall rules
- application logs under `data/logs/`
- `docker compose logs --tail=100 -f`

### A configuration file is missing

If `config.json` or `APPINFO.json` is absent, restart the application container. The entrypoint creates a missing default file without overwriting an existing one.