Martinhal-Contacts/Readme.md

# Martinhal Contact Management System - Docker Setup

## 🐳 Docker Installation (Recommended)

### Prerequisites
- Docker installed: https://docs.docker.com/get-docker/
- Docker Compose installed (usually comes with Docker Desktop)

### Quick Start with Docker

1. **Make sure you have all files in the same directory:**
```
martinhal-contacts/
├── Dockerfile
├── docker-compose.yml
├── .dockerignore
├── index.html
├── server.js
├── package.json
├── contacts_data.json (created automatically)
└── users_data.json   (created automatically on first run)
```

2. **Build and start the container:**
```bash
docker-compose up -d
```

3. **Access the application:**
Open your browser and go to: `http://localhost:8000`

4. **Stop the application:**
```bash
docker-compose down
```

5. **View logs:**
```bash
docker-compose logs -f
```

### Docker Commands Reference

**Start the application:**
```bash
docker-compose up -d
```

**Stop the application:**
```bash
docker-compose down
```

**Restart the application:**
```bash
docker-compose restart
```

**View logs:**
```bash
docker-compose logs -f martinhal-contacts
```

**Rebuild after code changes:**
```bash
docker-compose down
docker-compose build
docker-compose up -d
```

**Access container shell:**
```bash
docker exec -it martinhal-contacts sh
```

## 📦 Data Persistence

Docker volumes ensure your data persists:
- **contacts_data.json** - Your contact database (automatically backed up)
- **backups/** - Directory for backup files

Even if you delete and recreate containers, your data remains safe!

## 🔄 Updating the Application

1. Update your files (index.html, server.js, etc.)
2. Rebuild and restart:
```bash
docker-compose down
docker-compose build
docker-compose up -d
```

## 🔐 Authentication (v1.5)

There are **no hardcoded or default passwords** anywhere. Nothing on the site is visible until you sign in, and every account is created by an administrator.

### First time you open the site
On the very first visit **no account exists yet**, so the site shows a **"Create Admin Account"** screen. You choose the first administrator's username and password and you're signed in straight away. This one-time setup only appears when the site has no users — it is **not** shown when navigating to the admin section later.

### Signing in
After setup, opening the site shows a **login page**. By default sign-in is just **username + password** — there is no separate "view password" and no separate "admin password", the whole site is behind this single login.

### Two-factor authentication (optional)
**MFA is never mandatory.** Every account signs in with just a username and password unless that user chooses to turn on 2FA. Any user can enable it from **Profile → Two-factor authentication**: scan the QR code with an authenticator app (Google Authenticator, Authy, 1Password, Microsoft Authenticator…) and confirm a 6-digit code. Once enabled, that account's login also asks for the current code. The same panel lets the user **disable** it again at any time, returning to password-only sign-in.

### Users & roles
Signed-in administrators can open **Users** to add more accounts:
- **Administrator** accounts can view and edit the directory and manage users.
- **View-only** accounts can browse the directory but cannot edit it or manage users (the Admin button is hidden for them, and the server rejects any write attempts).

New users sign in with just their username and password; enabling 2FA is each user's own choice. Every user has a **profile with an uploadable avatar** and display name (the **Profile** button, available on every page after login).

### Changing your password
Any signed-in user (administrators included) can change their **own** password from **Profile → Change password**: enter the current password, then the new one twice. The new password must be at least 8 characters. After a successful change the account is signed out of any *other* active sessions, while the session you changed it from stays logged in.

### Footer
Every page shown **after login** displays the footer **"© 2026 Martinhal IT - Joao Vaz - Version 1.5"**. The login / create-admin screen intentionally has no footer.

### Resetting all accounts (start setup over)
Delete `users_data.json` and restart — the create-admin screen returns:
```bash
docker exec -it martinhal-contacts sh -c "rm -f users_data.json"
docker-compose restart
```

> ⚠️ `users_data.json` holds password hashes and MFA secrets. It is **never** served over HTTP and must be treated as sensitive. To keep accounts across container rebuilds, mount it as a volume (e.g. `- ./users_data.json:/app/users_data.json`).

## ⬆️ Updating from a previous version (no data loss)

This update ships **only code files** — it does **not** contain `contacts_data.json` or `users_data.json`, so unzipping it over your existing installation keeps all your contacts and accounts intact.

1. Unzip the update **into your existing project folder**, overwriting `index.html`, `server.js`, `package.json`, `Readme.md`, `dockerfile`, `docker-compose.yml` and `.dockerignore`. Your data files are left untouched.
2. Rebuild and restart the container (required because `server.js`/`package.json` changed):
```bash
docker-compose down
docker-compose build
docker-compose up -d
```
3. Existing accounts keep working. Any account that previously had MFA turned on will still be asked for its code (and can disable it from **Profile**); every other account now signs in with just username and password. If you're upgrading from the very first (pre-login) version and have no accounts yet, the site will show the create-admin screen on first load.

> `credentials.json` is no longer used and can be deleted; it is ignored by the app and the Docker build.

## 🛠 Troubleshooting

**Port 8000 already in use:**
Edit `docker-compose.yml` and change the port mapping:
```yaml
ports:
  - "3000:8000"  # Access via http://localhost:3000
```

**Container won't start:**
```bash
docker-compose logs martinhal-contacts
```

**Remove everything and start fresh:**
```bash
docker-compose down
docker system prune -a
docker-compose up -d
```

## 📋 Alternative: Manual Setup (No Docker)

If you don't want to use Docker:

### Step 1: Install Node.js
Download from: https://nodejs.org/

### Step 2: Install Dependencies
```bash
npm install
```

### Step 3: Start Server
```bash
npm start
```

### Step 4: Open Browser
```
http://localhost:8000
```

## 🎯 Production Deployment

For production deployment with Docker:

1. **Use environment variables for sensitive data**
2. **Set up HTTPS with reverse proxy (nginx)**
3. **Configure automated backups**
4. **Set resource limits in docker-compose.yml**

Example production docker-compose.yml:
```yaml
version: '3.8'
services:
  martinhal-contacts:
    build: .
    container_name: martinhal-contacts
    ports:
      - "8000:8000"
    volumes:
      - ./contacts_data.json:/app/contacts_data.json
      - ./backups:/app/backups
    restart: always
    environment:
      - NODE_ENV=production
    deploy:
      resources:
        limits:
          cpus: '0.5'
          memory: 512M
```

## ✅ Benefits of Docker

- ✅ **Consistent environment** - Works the same everywhere
- ✅ **Easy deployment** - One command to start
- ✅ **Isolated** - Doesn't interfere with other apps
- ✅ **Easy updates** - Rebuild and restart
- ✅ **Data persistence** - Your data is safe
- ✅ **Easy backups** - Just copy the volume

That's it! Your Martinhal Contact Management System is now running in Docker! 🎉