appa-net/zet.home.arpa/git-server/README.md

# Git Server Configuration

Gitea git server running on zet.home.arpa for managing internal repositories.

## Overview

**Software**: Gitea (Git with a cup of tea)  
**Version**: 1.25.4  
**Location**: zet.home.arpa (172.27.0.35)  
**URL**: http://172.27.0.35:3000/  
**User**: kenjim  
**Status**: Running and operational

## Installation Details

### Binary and Paths

| Component | Path | Details |
|-----------|------|---------|
| **Gitea Binary** | `/usr/local/bin/gitea` | Main executable |
| **Work Directory** | `/var/lib/gitea` | Data and repositories |
| **Custom Configuration** | `/var/lib/gitea/custom` | Custom templates, plugins, themes |
| **Config File** | `/etc/gitea/app.ini` | Gitea configuration (root-owned) |
| **System User** | `git` (UID 1002) | Service runs as this user |
| **System Group** | `git` (GID 1003) | Service group |

### Build Information

- **Build Tool**: GNU Make 4.3
- **Language**: Go 1.25.6
- **Database**: SQLite with unlock notifications
- **Binary Format**: bindata (self-contained assets)

### System Integration

**Systemd Service**: `gitea.service`

```
[Unit]
Description=Gitea (Git with a cup of tea)
After=network.target

[Service]
Type=simple
User=git
Group=git
WorkingDirectory=/var/lib/gitea
ExecStart=/usr/local/bin/gitea web --config /etc/gitea/app.ini
Restart=always
RestartSec=2s
Environment=USER=git HOME=/home/git GITEA_WORK_DIR=/var/lib/gitea

# Hardening
PrivateTmp=true
NoNewPrivileges=true

[Install]
WantedBy=multi-user.target
```

**Status**: 
- Enabled: Yes (auto-start on boot)
- Active: Yes (running since 2026-04-13 02:31:18 UTC)
- PID: 1074
- Memory: 170.5M (peak: 172.5M)

### Git Integration

- **Git Version**: 2.43.0
- **Git Home**: `/var/lib/gitea/data/home`
- **Git User**: git (system user)

## Network Configuration

### Web Interface

| Protocol | Address | Port | Status |
|----------|---------|------|--------|
| HTTP | 0.0.0.0 | 3000 | Active |
| HTTP | :: | 3000 | Active (IPv6) |

**Access URL**: http://172.27.0.35:3000

### SSH Access

| Protocol | Port | Status | Notes |
|----------|------|--------|-------|
| SSH | 22 | Active | Standard SSH port for Git operations |

**Clone URL Format**: `git@172.27.0.35:username/repo.git`

## Repository Configuration

### Repositories

Three repositories are configured:

#### 1. appa-net
- **Owner**: kenjim
- **Type**: Public
- **Status**: Empty
- **Created**: 2026-02-26
- **Last Updated**: 2026-02-26
- **Clone (SSH)**: `git@172.27.0.35:kenjim/appa-net.git`
- **Clone (HTTP)**: `http://172.27.0.35:3000/kenjim/appa-net.git`
- **Features Enabled**: Issues, Wiki, Pull Requests, Projects, Releases, Packages, Actions
- **Permissions**: Pull-only (no push permission)

#### 2. dotfiles
- **Owner**: kenjim
- **Type**: Public
- **Status**: Has code
- **Language**: Shell
- **Created**: 2026-02-23
- **Last Updated**: 2026-03-30
- **Clone (SSH)**: `git@172.27.0.35:kenjim/dotfiles.git`
- **Clone (HTTP)**: `http://172.27.0.35:3000/kenjim/dotfiles.git`
- **Features Enabled**: Issues, Wiki, Pull Requests, Projects, Releases, Packages, Actions
- **Size**: 265 KB

#### 3. test
- **Owner**: kenjim
- **Type**: Public
- **Status**: Empty
- **Created**: 2026-02-23
- **Last Updated**: 2026-02-23
- **Clone (SSH)**: `git@172.27.0.35:kenjim/test.git`
- **Clone (HTTP)**: `http://172.27.0.35:3000/kenjim/test.git`
- **Features Enabled**: Issues, Wiki, Pull Requests, Projects, Releases, Packages, Actions

### Repository Features

All repositories have standard Gitea features enabled:

- **Issues**: Time tracking, dependencies
- **Wiki**: Collaborative documentation
- **Pull Requests**: Code review with merge strategies
- **Projects**: Kanban-style boards
- **Releases**: Version management
- **Packages**: Package registry
- **Actions**: CI/CD pipelines

### Default Repository Settings

- **Merge Strategies**: 
  - Allow merge commits (default)
  - Allow rebase
  - Allow rebase explicit
  - Allow squash merge
  - Allow fast-forward only merge
  - Allow rebase update
- **Default Merge Style**: Merge
- **Maintainer Edit**: Not allowed by default
- **Auto-delete Branch**: Disabled
- **Whitespace Conflicts**: Not ignored

## Web Server Configuration

### Apache2

- **Status**: Installed but not reverse-proxying Gitea
- **Default Site**: `/etc/apache2/sites-available/000-default.conf`
- **Document Root**: `/var/www/html`
- **Gitea Access**: Direct on port 3000, not through Apache

Gitea runs as a standalone service, not behind Apache reverse proxy.

## Security Configuration

### Process Hardening

The Gitea systemd service has the following security settings:

- `PrivateTmp=true` — Private /tmp and /var/tmp
- `NoNewPrivileges=true` — Prevents privilege escalation

### User Isolation

- Runs as dedicated `git` system user
- Non-root execution
- Restricted home directory access

## Database

- **Type**: SQLite (embedded)
- **Features**: Unlock notifications enabled
- **Location**: `/var/lib/gitea/data/` (not directly accessible)

SQLite provides a simple, file-based database solution without needing a separate database server.

## API Access

### API Endpoint

**Base URL**: `http://172.27.0.35:3000/api/v1`

**Available Endpoints**:
- `/version` — API and Gitea version
- `/repos/search` — Search repositories
- User management, repository management, and more

### Authentication

- Token-based authentication
- User credentials can be generated in the web UI under Settings → Applications

## Logging

### Systemd Logs

View service logs:

```bash
journalctl -u gitea -n 20 --no-pager   # Last 20 lines
journalctl -u gitea -f                  # Follow live logs
systemctl status gitea --no-pager       # Service status
```

### Application Logs

Logs are written to the console/systemd journal and available through `journalctl`.

## File Permissions

| Path | Owner | Permissions | Notes |
|------|-------|-------------|-------|
| `/usr/local/bin/gitea` | root | 755 | Executable by all |
| `/var/lib/gitea` | git | 750 | Read/write by git user only |
| `/var/lib/gitea/custom` | git | 750 | Custom configuration |
| `/etc/gitea/app.ini` | root | 640 | Config readable by git group |

## Access Control

### Users

- **User**: kenjim
- **Created**: 2026-02-23
- **Email**: kenji@kenjim.com
- **Visibility**: Public profile

**Permissions**:
- No admin rights
- No push access to repositories (pull-only on current setup)

## Configuration Management

### Configuration File Location

The main configuration file is at `/etc/gitea/app.ini` but is not readable by unprivileged users.

To view or modify configuration:
1. SSH to zet.home.arpa
2. Use `sudo` to edit `/etc/gitea/app.ini`
3. Restart the service: `sudo systemctl restart gitea`

### Configuration Sections (Typical)

Common Gitea configuration includes:
- `[server]` — HTTP/HTTPS, domain, port
- `[database]` — Database connection
- `[repository]` — Repository settings
- `[ui]` — UI customization
- `[security]` — Security settings
- `[auth]` — Authentication configuration

## Managing the Service

### Start/Stop/Restart

```bash
sudo systemctl start gitea     # Start the service
sudo systemctl stop gitea      # Stop the service
sudo systemctl restart gitea   # Restart the service
sudo systemctl status gitea    # Check status
```

### Enable/Disable on Boot

```bash
sudo systemctl enable gitea    # Enable (already enabled)
sudo systemctl disable gitea   # Disable auto-start
```

### Backup Considerations

1. **Database**: Stored in `/var/lib/gitea/` (SQLite)
2. **Repositories**: In `/var/lib/gitea/repositories/`
3. **Configuration**: `/etc/gitea/app.ini`
4. **Custom Content**: `/var/lib/gitea/custom/`

**Backup Strategy**:
```bash
# As root, backup the entire gitea directory
sudo tar -czf gitea-backup-$(date +%Y-%m-%d).tar.gz \
  /var/lib/gitea /etc/gitea
```

## Cloning Repositories

### Using SSH

Requires SSH key setup. Clone format:

```bash
git clone git@172.27.0.35:kenjim/appa-net.git
```

### Using HTTPS

No authentication required for public repositories:

```bash
git clone http://172.27.0.35:3000/kenjim/appa-net.git
```

### Web Interface

Access repositories at: `http://172.27.0.35:3000/kenjim/repository-name`

## Pushing Changes

Current user permissions: **Pull-only**

To push changes:
1. Request admin permission in the repository settings, OR
2. Contact the repository administrator to grant push access

## Monitoring

### Memory Usage

Current:
- **Usage**: 170.5 MB
- **Peak**: 172.5 MB

Monitor over time:

```bash
watch -n 5 'ps aux | grep gitea | grep -v grep'
```

### Uptime

Service has been running since 2026-04-13 (9 days) without restart.

### Disk Usage

Check Gitea data directory:

```bash
du -sh /var/lib/gitea
du -sh /var/lib/gitea/repositories
```

## Troubleshooting

| Issue | Symptom | Solution |
|-------|---------|----------|
| Can't access web UI | Port 3000 unreachable | Check firewall rules, verify Gitea is running |
| SSH clone fails | Permission denied | Check SSH keys, verify user can access git@172.27.0.35 |
| Database locked | Gitea crashes on startup | Check `/var/lib/gitea/` permissions |
| High memory usage | Memory exceeding 200MB+ | Restart service, check for memory leaks |

## Future Enhancements

- [ ] Configure Apache2 reverse proxy for Gitea
- [ ] Enable HTTPS/TLS certificates
- [ ] Set up regular automated backups
- [ ] Configure LDAP or OAuth authentication
- [ ] Enable email notifications
- [ ] Configure webhooks for CI/CD
- [ ] Set up Actions/CI runners

---

**Last Updated**: 2026-04-22  
**Discovered**: During infrastructure investigation  
**Service Running Since**: 2026-04-13 02:31:18 UTC