# AssetManager 0.5.5.65

AssetManager is a self-hosted web application for managing IT equipment and other organizational assets. It provides asset inventory, software inventory, remote job execution, reporting, privacy/retention documentation, and optional integration with MeshCentral.

The project is licensed under the **Apache License 2.0** and may be used, modified, and redistributed for private and commercial purposes under the terms of that license.

## Features

- configurable asset categories, fields, status values, images, and assignments
- asset lists, detail views, history, bulk editing, Excel import/export, duplicate merging, and tree views
- hardware and software inventory with comparison and aggregation views
- job definitions and remote job execution with status tracking, callbacks, retries, and logs
- optional MeshCentral integration through the MeshCtrl command-line interface
- local users, optional LDAP/Active Directory authentication, and a protected local emergency administrator
- roles and asset visibility rules
- multilingual user interface, dark mode, charts, and configurable appearance
- integrated application backup and restore
- privacy and retention documentation with text, HTML, and Excel exports

## Requirements

- Docker Engine with Docker Compose
- a supported PostgreSQL container as defined by `docker-compose.yml`
- a suitable DNS name and HTTPS reverse proxy are recommended for production use
- optional: reachable MeshCentral instance
- optional: LDAP or Active Directory

## Installation

For a detailed first-start, image deployment, authentication, callback, update, and troubleshooting guide, see [`docs/INSTALLATION.md`](docs/INSTALLATION.md).


Create the local environment file:

```bash
cp .env.example .env
```

Set at least the required secrets in `.env`:

```env
POSTGRES_PASSWORD=CHANGE_ME
SESSION_SECRET=CHANGE_ME_LONG_RANDOM
LOCAL_ADMIN_USERNAME=emergency-admin
LOCAL_ADMIN_PASSWORD=CHANGE_ME_MIN_12_CHARS
```

Start the application:

```bash
docker compose up -d --build
```

By default, AssetManager is exposed on port `8088`.

### First start and authentication

On a fresh image-based installation, `config.json` and `APPINFO.json` are created automatically in `data/config/` if they do not exist. Existing files are never overwritten by the container entrypoint.

The default configuration starts with authentication disabled so the initial configuration can be completed. A prominent warning banner is displayed in the web interface while this mode is active. Before normal use:

1. Edit `data/config/config.json`.
2. Set `authentication.mode` to `local`.
3. Restart the application container with `docker compose restart app`.
4. Sign in with the protected local administrator configured through `LOCAL_ADMIN_USERNAME` and `LOCAL_ADMIN_PASSWORD` in `.env`.
5. Configure LDAP/Active Directory afterwards if required. The protected local administrator remains available as an emergency account.

Do not expose a fresh installation to untrusted networks while authentication is disabled.

## Persistent data

Runtime data is stored in bind mounts below `data/`:

```text
data/
├── config/       application configuration
├── postgres/     PostgreSQL database
├── uploads/      uploaded files
├── logs/         logs and diagnostics
├── backups/      application backups
└── scripts/      deployed scripts
```

Persistent runtime data and local secrets are intentionally kept outside the application image. See [SECURITY.md](SECURITY.md) and [docs/INSTALLATION.md](docs/INSTALLATION.md) for deployment guidance.

## Authentication

AssetManager supports local authentication and LDAP/Active Directory authentication. A protected local emergency administrator can be configured through environment variables so that administrative access remains possible if LDAP is unavailable.

LDAP debug logging is optional and should normally remain disabled. When disabled, LDAP logs contain only reduced authentication information.

## MeshCentral integration

MeshCentral integration is optional. AssetManager uses MeshCtrl for supported device queries, synchronization, presence information, file transfer, and remote jobs. AssetManager does not access the MeshCentral database directly.

MeshCentral and MeshCtrl are independent third-party projects and are not part of this repository. They are installed as dependencies during the Docker build.


## Dedicated callback listener

Docker deployments start a separate callback-only service together with the main application. The listener exposes only the software-job callback endpoint and its health check; the AssetManager web interface is not available on that port. `CALLBACK_BIND_IP` and `CALLBACK_PORT` control the host-side listener, while the public FQDN used by clients is configured in **Software and Jobs → Settings**.

The settings page provides separate health checks for the internal callback service and the configured/public callback address. See [`docs/INSTALLATION.md`](docs/INSTALLATION.md) for reverse-proxy and DMZ examples.

## Privacy and retention

The application includes a **Security & Privacy** section for documenting processing activities, data categories, retention periods, recipients, international transfers, technical and organizational measures, and deletion checks. Reports can be exported as text, HTML, or Excel.

Deletion functions are restricted to administrators. Exported reports do not include passwords, callback tokens, or other secrets.

## Updating

Back up `.env` and the complete `data/` directory before updating. Copy the new `assetmanager/` directory over the existing project directory and rebuild the application container:

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

Historical release notes are available in [`docs/version-history/`](docs/version-history/README.md).

## Security

Keep deployment secrets and persistent runtime data outside source control. Security reporting and deployment guidance is available in [SECURITY.md](SECURITY.md).

## Third-party components

Direct dependencies and license information are listed in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md). During the Docker build, license files from installed Python and Node.js packages are collected under `/app/THIRD_PARTY_LICENSES/`.

## Contributing

Contributions and bug reports are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for repository contribution requirements.

## License

Copyright © 2026 Roland Reich

Licensed under the Apache License, Version 2.0. See [LICENSE.txt](LICENSE.txt) for the complete license text.


Reusable asset/category images are persisted in `./data/uploads/library` and mounted into the application container.
