fmeshsync fix with synology,vm's and lxc

2026-08-08 19:44:27 +02:00
parent 2786f12ab6
commit 5e32be7d0c
41 changed files with 1335 additions and 1674 deletions
@@ -0,0 +1,233 @@
+# 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.