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:

docker-compose up -d

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

4. Stop the application:

docker-compose down

5. View logs:

docker-compose logs -f

Docker Commands Reference

Start the application:

docker-compose up -d

Stop the application:

docker-compose down

Restart the application:

docker-compose restart

View logs:

docker-compose logs -f martinhal-contacts

Rebuild after code changes:

docker-compose down
docker-compose build
docker-compose up -d

Access container shell:

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:

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:

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):

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:

ports:
  - "3000:8000"  # Access via http://localhost:3000

Container won't start:

docker-compose logs martinhal-contacts

Remove everything and start fresh:

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

npm install

Step 3: Start Server

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:

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! 🎉