first commit
This commit is contained in:
Stefano Manfredi
409
MULTI_ADMIN_SETUP.md
Normal file
409
MULTI_ADMIN_SETUP.md
Normal file
@@ -0,0 +1,409 @@
|
||||
# Multi-Admin Setup Guide
|
||||
|
||||
This guide explains how to configure org-stack for multiple administrators with proper permissions and shared access.
|
||||
|
||||
## Overview
|
||||
|
||||
By default, org-stack deploys to a user's home directory (`~/org-stack`). For production environments with multiple administrators, it's recommended to use a system-wide installation path with Unix group-based permissions.
|
||||
|
||||
## Architecture
|
||||
|
||||
**System-wide installation:**
|
||||
```
|
||||
/opt/org-stack/ # Installation root (deploy:orgstack, 750)
|
||||
├── .env # Configuration (deploy:orgstack, 640)
|
||||
├── compose.yml # Docker Compose definition
|
||||
├── secrets/ # Auto-generated secrets (750)
|
||||
│ ├── lldap/ # Individual secrets (600)
|
||||
│ └── authelia/
|
||||
├── data/ # Persistent Docker volumes
|
||||
│ ├── gitea/
|
||||
│ ├── wiki/
|
||||
│ └── ...
|
||||
└── backups/ # Backup storage (750)
|
||||
```
|
||||
|
||||
**Permissions:**
|
||||
- Directories: `750` (rwxr-x---) - Owner full access, group read+execute
|
||||
- Config files: `640` (rw-r-----) - Owner read+write, group read
|
||||
- Secrets: `600` (rw-------) - Owner only (Docker reads as owner)
|
||||
- Scripts: `750` (rwxr-x---) - Owner+group can execute
|
||||
|
||||
## One-Time Server Setup
|
||||
|
||||
These steps are performed **once** on the remote server by a sysadmin with sudo access.
|
||||
|
||||
### 1. Create Deployment User and Admin Group
|
||||
|
||||
```bash
|
||||
# Create the admin group
|
||||
sudo groupadd orgstack
|
||||
|
||||
# Create dedicated deployment user
|
||||
sudo useradd -r -m -d /opt/org-stack -s /bin/bash -g orgstack deploy
|
||||
|
||||
# Add deployment user to docker group (required for docker compose)
|
||||
sudo usermod -aG docker deploy
|
||||
|
||||
# Set password for deploy user (for SSH access)
|
||||
sudo passwd deploy
|
||||
```
|
||||
|
||||
### 2. Add Administrators to Group
|
||||
|
||||
```bash
|
||||
# Add each admin to the orgstack group
|
||||
sudo usermod -aG orgstack admin1
|
||||
sudo usermod -aG orgstack admin2
|
||||
sudo usermod -aG orgstack admin3
|
||||
|
||||
# Verify membership
|
||||
getent group orgstack
|
||||
# Output: orgstack:x:1001:admin1,admin2,admin3
|
||||
```
|
||||
|
||||
**Important**: Admins must log out and log back in for group membership to take effect.
|
||||
|
||||
### 3. Create Installation Directory
|
||||
|
||||
```bash
|
||||
# Create directory structure
|
||||
sudo mkdir -p /opt/org-stack
|
||||
|
||||
# Set ownership
|
||||
sudo chown -R deploy:orgstack /opt/org-stack
|
||||
|
||||
# Set permissions
|
||||
sudo chmod 750 /opt/org-stack
|
||||
```
|
||||
|
||||
### 4. Configure SSH Access
|
||||
|
||||
Each admin needs SSH access to the `deploy` user:
|
||||
|
||||
**Option A: SSH Key Authentication (recommended)**
|
||||
```bash
|
||||
# On admin's local machine, copy SSH key
|
||||
ssh-copy-id deploy@your-server.com
|
||||
|
||||
# Test access
|
||||
ssh deploy@your-server.com
|
||||
```
|
||||
|
||||
**Option B: Password Authentication**
|
||||
```bash
|
||||
# Ensure password authentication is enabled in /etc/ssh/sshd_config
|
||||
# PasswordAuthentication yes
|
||||
|
||||
# Admins use the deploy user password
|
||||
ssh deploy@your-server.com
|
||||
```
|
||||
|
||||
### 5. Optional: Sudo Access for Admins
|
||||
|
||||
If admins need to perform system tasks (install packages, restart services):
|
||||
|
||||
```bash
|
||||
# Create sudoers file for orgstack group
|
||||
sudo visudo -f /etc/sudoers.d/orgstack
|
||||
```
|
||||
|
||||
Add:
|
||||
```
|
||||
# Allow orgstack group members to run docker commands
|
||||
%orgstack ALL=(ALL) NOPASSWD: /usr/bin/docker, /usr/bin/docker-compose
|
||||
|
||||
# Or give full sudo access
|
||||
%orgstack ALL=(ALL) ALL
|
||||
```
|
||||
|
||||
## Local Deployment Configuration
|
||||
|
||||
Each admin configures their **local** `.env` file on their workstation (not on the server).
|
||||
|
||||
### 1. Clone Repository Locally
|
||||
|
||||
```bash
|
||||
git clone https://github.com/yourorg/org-stack.git
|
||||
cd org-stack
|
||||
```
|
||||
|
||||
### 2. Configure .env for Multi-Admin
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
nano .env
|
||||
```
|
||||
|
||||
**Required settings:**
|
||||
```bash
|
||||
# Domain
|
||||
BASE_DOMAIN=yourdomain.com
|
||||
|
||||
# Remote server connection (all admins use the same deploy user)
|
||||
REMOTE_USER=deploy
|
||||
REMOTE_HOST=your-server.com
|
||||
REMOTE_PORT=22
|
||||
|
||||
# Multi-admin configuration
|
||||
REMOTE_PATH=/opt/org-stack # System-wide installation
|
||||
ADMIN_GROUP=orgstack # Unix group for permissions
|
||||
|
||||
# SMTP, 2FA, etc. (same for all admins)
|
||||
REQUIRE_2FA=true
|
||||
# ... other settings ...
|
||||
```
|
||||
|
||||
### 3. Deploy from Local Machine
|
||||
|
||||
```bash
|
||||
./deploy.sh
|
||||
```
|
||||
|
||||
The script will:
|
||||
1. Sync files to `/opt/org-stack` on remote server
|
||||
2. Set group ownership to `orgstack`
|
||||
3. Set permissions (750 for dirs, 640 for files, 600 for secrets)
|
||||
4. Generate secrets if missing
|
||||
5. Start Docker services
|
||||
|
||||
## Admin Workflows
|
||||
|
||||
### Deploying Changes
|
||||
|
||||
Any admin can deploy changes:
|
||||
|
||||
```bash
|
||||
# On local machine
|
||||
cd ~/org-stack
|
||||
git pull # Get latest changes
|
||||
nano .env # Modify configuration if needed
|
||||
./deploy.sh
|
||||
```
|
||||
|
||||
### Managing Services Remotely
|
||||
|
||||
```bash
|
||||
# From local machine using manage.sh
|
||||
./manage.sh status
|
||||
./manage.sh logs authelia
|
||||
./manage.sh restart
|
||||
|
||||
# Or SSH directly to server
|
||||
ssh deploy@your-server.com
|
||||
cd /opt/org-stack
|
||||
docker compose ps
|
||||
docker compose logs -f authelia
|
||||
docker compose restart gitea
|
||||
```
|
||||
|
||||
### Viewing Configuration
|
||||
|
||||
All group members can read configs:
|
||||
|
||||
```bash
|
||||
ssh deploy@your-server.com
|
||||
cd /opt/org-stack
|
||||
cat .env
|
||||
cat secrets/lldap/LDAP_USER_PASS
|
||||
docker compose config # Show resolved configuration
|
||||
```
|
||||
|
||||
### Making Changes on Server
|
||||
|
||||
**Only the `deploy` user can modify files** (write permission). Admins must either:
|
||||
|
||||
**Option A: Deploy from local machine (recommended)**
|
||||
```bash
|
||||
# Edit .env locally, then deploy
|
||||
./deploy.sh
|
||||
```
|
||||
|
||||
**Option B: SSH as deploy user**
|
||||
```bash
|
||||
ssh deploy@your-server.com
|
||||
cd /opt/org-stack
|
||||
nano .env
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
**Option C: Use sudo (if configured)**
|
||||
```bash
|
||||
ssh admin1@your-server.com
|
||||
cd /opt/org-stack
|
||||
sudo -u deploy nano .env
|
||||
sudo -u deploy docker compose up -d
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### File Permissions
|
||||
|
||||
- **Secrets are owner-only (600)**: Only `deploy` user and Docker can read secrets
|
||||
- **Configs are group-readable (640)**: Admins can audit configuration
|
||||
- **No world access**: All files are 750/640/600 (no "others" permission)
|
||||
|
||||
### SSH Key Management
|
||||
|
||||
- Each admin should use their own SSH key to authenticate as `deploy` user
|
||||
- Use `~deploy/.ssh/authorized_keys` to manage who has access
|
||||
- Revoke access by removing admin's key from authorized_keys
|
||||
|
||||
### Audit Trail
|
||||
|
||||
Track who deployed what:
|
||||
|
||||
```bash
|
||||
# On server, check file modification times
|
||||
ls -la /opt/org-stack/.env
|
||||
|
||||
# Check who's currently logged in as deploy
|
||||
who
|
||||
|
||||
# SSH logs show authentication
|
||||
sudo journalctl -u ssh | grep deploy
|
||||
```
|
||||
|
||||
### Backup Strategy
|
||||
|
||||
Only `deploy` user can create backups:
|
||||
|
||||
```bash
|
||||
# From local machine
|
||||
./manage.sh backup
|
||||
|
||||
# Or on server as deploy
|
||||
ssh deploy@your-server.com
|
||||
cd /opt/org-stack
|
||||
docker compose exec registration python backup.py
|
||||
```
|
||||
|
||||
Backups are stored in `/opt/org-stack/backups/` with 750 permissions (group-readable).
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Permission Denied Errors
|
||||
|
||||
**Error:** `Permission denied: /opt/org-stack`
|
||||
|
||||
**Solution:** Ensure you're SSHing as `deploy` user:
|
||||
```bash
|
||||
ssh deploy@your-server.com # Not your personal user
|
||||
```
|
||||
|
||||
**Error:** `Failed to set group ownership`
|
||||
|
||||
**Solution:** Verify `deploy` user is in `orgstack` group:
|
||||
```bash
|
||||
groups deploy
|
||||
# Should show: deploy : orgstack docker
|
||||
```
|
||||
|
||||
### Group Membership Not Working
|
||||
|
||||
Admins must **log out and back in** after being added to group:
|
||||
```bash
|
||||
# On server
|
||||
exit
|
||||
ssh deploy@your-server.com
|
||||
groups # Should now show orgstack
|
||||
```
|
||||
|
||||
### Docker Permission Denied
|
||||
|
||||
**Error:** `permission denied while trying to connect to Docker daemon`
|
||||
|
||||
**Solution:** Add `deploy` user to `docker` group:
|
||||
```bash
|
||||
sudo usermod -aG docker deploy
|
||||
# Log out and back in
|
||||
```
|
||||
|
||||
### Secrets Not Readable by Docker
|
||||
|
||||
**Error:** Container fails to start, can't read secret file
|
||||
|
||||
**Cause:** Secrets have 600 permissions, readable only by owner
|
||||
|
||||
**Solution:** This is correct! Docker runs containers as the file owner, so 600 is appropriate. Verify:
|
||||
```bash
|
||||
ls -l /opt/org-stack/secrets/lldap/LDAP_USER_PASS
|
||||
# Should show: -rw------- 1 deploy orgstack
|
||||
```
|
||||
|
||||
## Migration from Single-User Setup
|
||||
|
||||
If you're currently using `~/org-stack` and want to migrate to multi-admin:
|
||||
|
||||
### 1. Backup Current Deployment
|
||||
|
||||
```bash
|
||||
ssh user@server
|
||||
cd ~/org-stack
|
||||
docker compose down
|
||||
tar czf ~/org-stack-backup.tar.gz data/ secrets/ .env
|
||||
```
|
||||
|
||||
### 2. Perform One-Time Server Setup
|
||||
|
||||
Follow steps in "One-Time Server Setup" section above.
|
||||
|
||||
### 3. Restore Data to New Location
|
||||
|
||||
```bash
|
||||
# Extract backup
|
||||
sudo tar xzf ~/org-stack-backup.tar.gz -C /opt/org-stack/
|
||||
|
||||
# Fix permissions
|
||||
sudo chown -R deploy:orgstack /opt/org-stack
|
||||
cd /opt/org-stack
|
||||
sudo -u deploy bash
|
||||
find . -type d -exec chmod 750 {} \;
|
||||
find . -type f -exec chmod 640 {} \;
|
||||
find secrets -type f -exec chmod 600 {} \;
|
||||
```
|
||||
|
||||
### 4. Update Local .env
|
||||
|
||||
```bash
|
||||
# On local machine
|
||||
nano .env
|
||||
# Change: REMOTE_DIR=org-stack
|
||||
# To: REMOTE_PATH=/opt/org-stack
|
||||
# ADMIN_GROUP=orgstack
|
||||
```
|
||||
|
||||
### 5. Deploy
|
||||
|
||||
```bash
|
||||
./deploy.sh
|
||||
```
|
||||
|
||||
## Alternative: Single Admin with System Path
|
||||
|
||||
If you want system-wide path but don't need multi-admin:
|
||||
|
||||
```bash
|
||||
# In .env
|
||||
REMOTE_PATH=/opt/org-stack
|
||||
ADMIN_GROUP= # Leave empty for single-user mode
|
||||
```
|
||||
|
||||
Permissions will be standard (owner-only) without group access.
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Use version control**: Keep `.env.example` in git, but never commit `.env`
|
||||
2. **Document changes**: Use git commit messages to track infrastructure changes
|
||||
3. **Test in staging**: Use `USE_SELF_SIGNED_CERTS=true` for testing deployments
|
||||
4. **Regular backups**: Schedule automated backups with `./manage.sh backup`
|
||||
5. **Audit access**: Regularly review `~deploy/.ssh/authorized_keys`
|
||||
6. **Rotate secrets**: Periodically regenerate secrets (requires coordination)
|
||||
7. **Communication**: Coordinate deployments among team (avoid conflicts)
|
||||
|
||||
## See Also
|
||||
|
||||
- [README.md](README.md) - Main documentation
|
||||
- [ARCHITECTURE.md](ARCHITECTURE.md) - Technical architecture details
|
||||
- [deploy.sh](deploy.sh) - Deployment script source
|
||||
- [manage.sh](manage.sh) - Management operations
|
||||
Reference in New Issue
Block a user