# ADL System Installation Guide for Linux
## Prerequisites
- Linux operating system (Ubuntu 20.04+, Debian 11+, CentOS 8+, or similar)
- Node.js 18 or higher
- npm (comes with Node.js)
- Git (optional, for cloning)
## Quick Start
### 1. Install Node.js (if not already installed)
#### Ubuntu/Debian:
```bash
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
```
#### CentOS/RHEL:
```bash
curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash -
sudo yum install -y nodejs
```
### 2. Install Dependencies
```bash
npm install
```
### 3. Start the System
#### Option A: Using the startup script
```bash
chmod +x start.sh
./start.sh
```
#### Option B: Using npm
```bash
npm start
```
#### Option C: Start services individually
```bash
# Terminal 1 - GraphQL Server
npm run start:graphql
# Terminal 2 - UI Server (in a new terminal)
npm run start:ui
# Terminal 3 - MCP Server (optional, in a new terminal)
npm run start:mcp
```
### 4. Access the Application
- **Web UI**: http://localhost:3000
- **GraphQL Playground**: http://localhost:4000/graphql
## Docker Deployment
### Using Docker Compose (Recommended)
```bash
# Build and start
docker-compose up -d
# View logs
docker-compose logs -f
# Stop
docker-compose down
```
### Using Docker directly
```bash
# Build image
docker build -t adl-system .
# Run container
docker run -d \
-p 3000:3000 \
-p 4000:4000 \
-v $(pwd)/data:/app/data \
--name adl-system \
adl-system
# View logs
docker logs -f adl-system
# Stop container
docker stop adl-system
docker rm adl-system
```
## Systemd Service (Linux System Service)
To run ADL as a system service:
### 1. Create service file
```bash
sudo nano /etc/systemd/system/adl.service
```
### 2. Add the following content:
```ini
[Unit]
Description=Architectural Decision Log System
After=network.target
[Service]
Type=simple
User=your-username
WorkingDirectory=/path/to/ADL
ExecStart=/usr/bin/node scripts/start-all.js
Restart=on-failure
RestartSec=10
StandardOutput=syslog
StandardError=syslog
SyslogIdentifier=adl-system
[Install]
WantedBy=multi-user.target
```
### 3. Enable and start the service
```bash
sudo systemctl daemon-reload
sudo systemctl enable adl
sudo systemctl start adl
sudo systemctl status adl
```
## Configuration
### Environment Variables
Create a `.env` file in the root directory:
```bash
GRAPHQL_PORT=4000
UI_PORT=3000
NODE_ENV=production
```
### Port Configuration
- GraphQL server port: Set `GRAPHQL_PORT` environment variable (default: 4000)
- UI server port: Set `UI_PORT` environment variable (default: 3000)
## Firewall Configuration
If you're running a firewall, allow traffic on ports 3000 and 4000:
```bash
# UFW (Ubuntu)
sudo ufw allow 3000
sudo ufw allow 4000
# firewalld (CentOS/RHEL)
sudo firewall-cmd --permanent --add-port=3000/tcp
sudo firewall-cmd --permanent --add-port=4000/tcp
sudo firewall-cmd --reload
```
## Reverse Proxy (Nginx)
For production deployment with SSL:
```nginx
server {
listen 80;
server_name your-domain.com;
location / {
proxy_pass http://localhost:3000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';
proxy_set_header Host $host;
proxy_cache_bypass $http_upgrade;
}
location /graphql {
proxy_pass http://localhost:4000/graphql;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';
proxy_set_header Host $host;
proxy_cache_bypass $http_upgrade;
}
}
```
## Troubleshooting
### Check if services are running
```bash
# Check processes
ps aux | grep node
# Check ports
netstat -tulpn | grep -E '3000|4000'
```
### View logs
```bash
# If running with npm
npm start 2>&1 | tee adl.log
# If running as systemd service
sudo journalctl -u adl -f
```
### Database location
The SQLite database is stored in `./data/adl.sqlite`
## Stopping the System
```bash
# Using the stop script
chmod +x stop.sh
./stop.sh
# Or manually
pkill -f "node.*graphql-server.js"
pkill -f "node.*ui/server.js"
```
## Backup
To backup your data:
```bash
# Backup database
cp data/adl.sqlite data/adl.sqlite.backup-$(date +%Y%m%d)
# Or create a full backup
tar -czf adl-backup-$(date +%Y%m%d).tar.gz data/
```
## Support
For issues or questions, please refer to the main README.md file.
