ame-job-manager/CHANGES.md

# Changes — SMB Network Share Support

## Overview
Updated the AME Remote Job Manager to support automatic SMB share mounting on container startup. The Docker container can now mount `//172.18.210.5/ame` using credentials configured through the Settings GUI.

## Files Changed

### 1. `entrypoint.sh` (NEW)
Shell script that runs when the container starts. Responsibilities:
- Read SMB credentials from `/data/settings.json` (populated by the Settings API)
- Mount the SMB share at `/mnt/smb-share` using `mount -t cifs`
- Create subdirectories on the SMB share: `watch`, `output`, `logs`
- Bind-mount these to `/watch`, `/output`, `/ame-logs` inside the container
- Fall back gracefully if SMB mount fails (uses Docker volumes as fallback)
- Start the Node.js application

**Key features:**
- Reads settings from the persistent `/data` volume
- Handles missing credentials gracefully
- Provides clear logging of mount success/failure
- Automatically creates required subdirectories

### 2. `Dockerfile` (UPDATED)
Changes:
- Added `cifs-utils` and `util-linux` packages for SMB mounting support
- Added `bash` package for entrypoint script execution
- Copy `entrypoint.sh` into the image and make it executable
- Changed `CMD` to use `ENTRYPOINT` with the shell script

**Before:**
```dockerfile
FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install --production
COPY . .
EXPOSE 3100
CMD ["node", "server.js"]
```

**After:**
```dockerfile
FROM node:20-alpine
RUN apk add --no-cache cifs-utils bash util-linux
WORKDIR /app
COPY package*.json ./
RUN npm install --production
COPY . .
COPY entrypoint.sh ./
RUN chmod +x ./entrypoint.sh
EXPOSE 3100
ENTRYPOINT ["./entrypoint.sh"]
```

### 3. `docker-compose.yml` (UPDATED)
Changes:
- Added `cap_add: [SYS_ADMIN]` — required for mounting filesystems inside container
- Added `security_opt: [apparmor=unconfined]` — allows mount operations
- Changed volume setup to use Docker-managed volumes as fallback (entrypoint.sh will bind-mount SMB to these)
- Added `DATA_DIR=/data` environment variable for settings persistence
- Updated comments to clarify the SMB mounting flow

**Key additions:**
```yaml
cap_add:
  - SYS_ADMIN
security_opt:
  - apparmor=unconfined
```

### 4. `README.md` (UPDATED)
Added comprehensive new section: "SMB Network Share Configuration"

**New content includes:**
- How automatic SMB mounting works (3-step process)
- Step-by-step configuration instructions (5 steps)
- Instructions for creating subdirectories on the SMB share
- Troubleshooting guide for common mount issues
- Alternative approach for pre-mounted SMB shares
- Updated Prerequisites section with SMB requirements

## How It Works (User Flow)

1. **Container starts** → `entrypoint.sh` runs
2. **Script reads** → `/data/settings.json` for SMB credentials
3. **If credentials present** → `mount -t cifs //172.18.210.5/ame /mnt/smb-share` with auth
4. **Creates subdirectories** → `watch`, `output`, `logs` on the mounted share
5. **Bind-mounts** → `/mnt/smb-share/watch → /watch`, etc.
6. **Node.js starts** → sees `/watch`, `/output`, `/ame-logs` as local paths
7. **User configures SMB** → through Settings GUI in web UI
8. **User restarts container** → mounts SMB on next startup

## Backward Compatibility

✅ **Fully backward compatible:**
- If no SMB credentials are configured, the entrypoint falls back to Docker-managed volumes
- Existing deployments that bind-mount SMB at the host level continue to work
- The entrypoint checks `if [ -f "$SETTINGS_FILE" ]` before reading — graceful on first boot

## Security Notes

- **Passwords never exposed**: SMB password stored server-side in `/data/settings.json`, never sent to browser
- **Settings API masks password**: Returns `smbPasswordSet: true/false` indicator, never the actual password
- **Credentials at rest**: Only stored in the `/data` volume (which should be on secure storage)
- **Network transmission**: Use HTTPS/TLS in production to protect credentials in transit

## Testing Checklist

- [ ] Build Docker image: `docker compose build`
- [ ] Start container: `docker compose up -d`
- [ ] Check logs: `docker logs ame-job-manager` (look for mount messages)
- [ ] Access UI: `http://localhost:3100`
- [ ] Open Settings, enter SMB credentials
- [ ] Save settings
- [ ] Restart container: `docker compose restart`
- [ ] Verify SMB mount: `docker exec ame-job-manager mount | grep cifs`
- [ ] Verify bind-mounts: `docker exec ame-job-manager ls -la /watch /output /ame-logs`
- [ ] Upload a `.prproj` file and verify it appears on the SMB share

## Deployment Instructions

1. Pull the latest code
2. Update `docker-compose.yml` with any local customizations
3. Ensure the SMB machine has subdirectories created:
   - `\\172.18.210.5\ame\watch`
   - `\\172.18.210.5\ame\output`
   - `\\172.18.210.5\ame\logs`
4. Start/restart the container: `docker compose up -d`
5. Configure SMB credentials in Settings → save → restart container

## Rollback

If you need to revert to the previous version:
1. Checkout the previous commit
2. Comment out the `cap_add` and `security_opt` lines in `docker-compose.yml`
3. Rebuild and restart

All changes are additive and don't break existing functionality.