Skip to content

Commit 7b13606

Browse files
perigrinperigrin
authored
Base Infrastructure Setup with Fly.io Foundation (#18)
2 parents aa295bf + 73f4f81 commit 7b13606

File tree

14 files changed

+2782
-0
lines changed

14 files changed

+2782
-0
lines changed

‎.github/workflows/fly.yml‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
# ABOUTME: GitHub Actions workflow for automated Fly.io deployment
2+
# ABOUTME: Follows Fly.io best practices with simple flyctl deploy commands
3+
4+
name: Deploy to Fly.io
5+
6+
on:
7+
push:
8+
branches: [main]
9+
10+
env:
11+
FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}
12+
13+
jobs:
14+
test:
15+
name: Run Tests
16+
runs-on: ubuntu-latest
17+
steps:
18+
- uses: actions/checkout@v4
19+
20+
- name: Setup Perl
21+
uses: shogo82148/actions-setup-perl@v1
22+
with:
23+
perl-version: '5.38'
24+
25+
- name: Install Test Dependencies
26+
run: cpanm --quiet --notest Test2::V0
27+
28+
- name: Run Infrastructure Tests
29+
run: prove -v t/
30+
31+
setup-infrastructure:
32+
name: Setup Infrastructure
33+
runs-on: ubuntu-latest
34+
needs: test
35+
if: github.ref == 'refs/heads/main'
36+
steps:
37+
- uses: actions/checkout@v4
38+
- uses: superfly/flyctl-actions/setup-flyctl@master
39+
40+
- name: Setup Perl
41+
uses: shogo82148/actions-setup-perl@v1
42+
with:
43+
perl-version: '5.38'
44+
45+
- name: Create PostgreSQL Database
46+
run: |
47+
# Check if magnet-postgres already exists
48+
if ! flyctl apps list | grep -q "magnet-postgres"; then
49+
echo "Creating PostgreSQL database..."
50+
flyctl postgres create --name magnet-postgres --region ord --initial-cluster-size 1
51+
else
52+
echo "PostgreSQL database already exists"
53+
fi
54+
55+
- name: Create Volumes
56+
run: perl scripts/create-volumes.pl --production
57+
58+
- name: Setup Deploy Tokens
59+
run: perl scripts/setup-deploy-tokens.pl
60+
61+
deploy:
62+
name: Deploy Applications
63+
runs-on: ubuntu-latest
64+
needs: setup-infrastructure
65+
strategy:
66+
matrix:
67+
include:
68+
- app: magnet-9rl
69+
config: servers/magnet-9rl/fly.toml
70+
region: ord
71+
- app: magnet-1eu
72+
config: servers/magnet-1eu/fly.toml
73+
region: ams
74+
- app: magnet-atheme
75+
config: servers/magnet-atheme/fly.toml
76+
region: ord
77+
steps:
78+
- uses: actions/checkout@v4
79+
- uses: superfly/flyctl-actions/setup-flyctl@master
80+
81+
- name: Attach PostgreSQL to magnet-atheme
82+
if: matrix.app == 'magnet-atheme'
83+
run: |
84+
# Check if already attached
85+
if ! flyctl postgres attach --app magnet-atheme magnet-postgres --dry-run 2>/dev/null; then
86+
echo "Attaching PostgreSQL to magnet-atheme..."
87+
flyctl postgres attach --app magnet-atheme magnet-postgres
88+
else
89+
echo "PostgreSQL already attached to magnet-atheme"
90+
fi
91+
92+
- name: Deploy ${{ matrix.app }}
93+
run: flyctl deploy --config ${{ matrix.config }} --app ${{ matrix.app }} --remote-only

‎.gitignore‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# PVX local modules
2+
local/
3+
4+
# Claude Code private files
5+
.claude/
6+
CLAUDE.md
7+
8+
# Temporary files
9+
*.tmp
10+
*.bak
11+
12+
# OS files
13+
.DS_Store
14+
Thumbs.db
15+
16+
# Editor files
17+
*~
18+
.*.swp
19+
.*.swo
20+
21+
# Log files
22+
*.log

‎README.md‎

Lines changed: 263 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,263 @@
1+
# Magnet IRC Network
2+
3+
A modern, distributed IRC network infrastructure built for irc.perl.org with
4+
multi-region deployment.
5+
6+
## Overview
7+
8+
The Magnet IRC Network is IRC infrastructure that provides reliable, secure,
9+
and performant IRC services across multiple geographic regions. Built using
10+
Solanum IRCd and Atheme services, it leverages Fly.io's global infrastructure
11+
and Tailscale's mesh networking for secure inter-server communication.
12+
13+
### Key Features
14+
15+
- **Multi-Region Deployment**: US (Chicago) and EU (Amsterdam) regions for
16+
optimal global performance
17+
- **Security-First Design**: Tailscale mesh networking, ephemeral
18+
authentication keys, auto-generated passwords
19+
- **High Availability**: Geographic redundancy with automatic failover
20+
capabilities
21+
- **Modern Infrastructure**: Container-based deployment with proper health
22+
checks and monitoring
23+
24+
## Architecture
25+
26+
```
27+
┌─────────────────┐ Tailscale ┌─────────────────┐
28+
│ magnet-9RL │◄─────────────────►│ magnet-1EU │
29+
│ (US Hub/IRC) │ Private Mesh │ (EU IRC) │
30+
│ SID: 9RL │ │ SID: 1EU │
31+
│ OpenSSL+EPYC │ │ OpenSSL+EPYC │
32+
└─────────────────┘ └─────────────────┘
33+
│ │
34+
▼ ▼
35+
┌─────────────────┐ Tailscale ┌─────────────────┐
36+
│ magnet-atheme │◄─────────────────►│ magnet-postgres │
37+
│ (US Services) │ Private Mesh │ (Fly MPG) │
38+
│ OpenSSL+EPYC │ │ │
39+
└─────────────────┘ └─────────────────┘
40+
```
41+
42+
### Components
43+
44+
1. **magnet-9RL** - Primary IRC server (US/Chicago)
45+
- Solanum IRCd with OpenSSL optimizations
46+
- Hub server for network coordination
47+
- SSL/TLS client connections on port 6697
48+
49+
2. **magnet-1EU** - Secondary IRC server (EU/Amsterdam)
50+
- Solanum IRCd with OpenSSL optimizations
51+
- Linked to US hub for global federation
52+
- Regional optimization for European users
53+
54+
3. **magnet-atheme** - IRC Services (US/Chicago)
55+
- User registration and authentication (NickServ)
56+
- Channel management services (ChanServ)
57+
- Persistent data storage via PostgreSQL
58+
59+
4. **magnet-postgres** - Database (US/Chicago)
60+
- PostgreSQL database for services persistence
61+
- User accounts, channel registrations, configurations
62+
- Automated backups and high availability
63+
64+
## Getting Started
65+
66+
### Prerequisites
67+
68+
- Access to the perl-irc Github organization
69+
- [Fly.io CLI](https://fly.io/docs/hands-on/install-flyctl/) installed and authenticated
70+
- Access to the `magnet-irc` Fly.io organization
71+
- Tailscale account with access to the `perl-irc` organization
72+
- Basic familiarity with IRC network administration
73+
74+
## Deployment
75+
76+
### Development Deployment
77+
78+
For testing and development purposes, use development-specific app names to avoid
79+
conflicts with production:
80+
81+
```bash
82+
# Create development apps with -dev suffix
83+
fly apps create magnet-hub-dev --org magnet-irc
84+
fly apps create magnet-atheme-dev --org magnet-irc
85+
86+
# Set up Tailscale authentication for dev
87+
fly secrets set TAILSCALE_AUTHKEY=tskey-auth-xxxxx --app magnet-9rl-dev
88+
89+
# Deploy base infrastructure (development)
90+
fly deploy --app magnet-hub-dev
91+
fly deploy --app magnet-atheme-dev
92+
93+
# Validate mesh connectivity
94+
fly ssh console --app magnet-hub-dev
95+
tailscale status
96+
```
97+
98+
**Important**: Always use the `-dev` suffix for development deployments to prevent
99+
conflicts with production infrastructure.
100+
101+
### Production Deployment
102+
103+
Follow the systematic approach outlined in `github-issues.md`:
104+
105+
1. **Start with Issue #1** - Implement base infrastructure with proper testing
106+
2. **Follow TDD methodology** - Write failing tests, implement minimal code to pass
107+
3. **Validate each step** - Ensure all tests pass before proceeding
108+
4. **Build incrementally** - Each issue adds functionality while maintaining stability
109+
110+
## Configuration
111+
112+
### Key Environment Variables
113+
114+
- `SERVER_NAME` - Unique server identifier (magnet-9RL, magnet-1EU)
115+
- `SERVER_SID` - Three-character server ID for IRC protocol
116+
- `SERVER_DESCRIPTION` - Human-readable server description
117+
- `TAILSCALE_AUTHKEY` - Ephemeral auth key for mesh networking
118+
- `SERVICES_PASSWORD` - Authentication between IRC server and services
119+
- `LINK_PASSWORD_9RL_1EU` - Authentication between linked IRC servers
120+
121+
### Configuration Templates
122+
123+
The project uses environment variable substitution in configuration templates:
124+
125+
- `ircd.conf.template` - Solanum server configuration
126+
- `atheme.conf.template` - Atheme services configuration
127+
- Startup scripts handle dynamic password generation and Tailscale initialization
128+
129+
## Security
130+
131+
### Security Features
132+
133+
- **Ephemeral Tailscale Keys** - Devices automatically cleaned up on container termination
134+
- **Auto-Generated Passwords** - 24-32 character secure passwords for all inter-service communication
135+
- **SSL/TLS Everywhere** - All client and server-to-server communications encrypted
136+
- **Private Mesh Networking** - Inter-server communication isolated via Tailscale
137+
- **AMD EPYC Optimizations** - Hardware-accelerated cryptography with OpenSSL
138+
139+
### Security Best Practices
140+
141+
- No passwords stored in plain text or logs
142+
- Secure credential distribution via Fly.io secrets
143+
- Network isolation from public internet for internal communication
144+
- Regular password rotation capabilities
145+
- Comprehensive security audit coverage in test suite
146+
147+
## Performance
148+
149+
### Optimization Features
150+
151+
- **OpenSSL with AES-NI** acceleration on AMD EPYC processors
152+
- **Multi-core compilation** during Docker builds
153+
- **Optimized connection classes** for different user types and regions
154+
- **Efficient resource allocation** (1-2GB RAM, 1-2 vCPUs per service)
155+
- **Geographic distribution** for optimal user experience
156+
157+
### Performance Monitoring
158+
159+
The project includes comprehensive performance testing:
160+
- Response time measurement and SLA establishment
161+
- Throughput testing under load
162+
- Resource utilization monitoring
163+
- Capacity planning metrics
164+
- Performance regression detection
165+
166+
## Troubleshooting
167+
168+
### Common Operations
169+
170+
```bash
171+
# Check application status
172+
fly status --app magnet-9rl
173+
174+
# View logs
175+
fly logs --app magnet-9rl
176+
177+
# SSH into container
178+
fly ssh console --app magnet-9rl
179+
180+
# Check Tailscale mesh status
181+
tailscale status
182+
183+
# Monitor SSL connections
184+
netstat -an | grep :6697
185+
186+
# Test OpenSSL performance
187+
openssl speed aes-256-cbc
188+
189+
# Verify AMD EPYC features
190+
cat /proc/cpuinfo | grep flags
191+
```
192+
193+
### Health Checks
194+
195+
All components include comprehensive health checks:
196+
- Tailscale mesh connectivity
197+
- IRC server responsiveness
198+
- Services authentication status
199+
- Database connectivity
200+
- SSL certificate validity
201+
202+
## Development
203+
204+
### Contributing
205+
206+
1. **Use GitHub Issues** - Follow the systematic 15-issue implementation plan
207+
2. **Maintain Documentation** - Update relevant documentation with changes
208+
3. **Test Thoroughly** - Ensure all tests pass before submitting changes
209+
4. **Security Review** - Consider security implications of all changes
210+
211+
### Testing
212+
213+
The project emphasizes comprehensive testing:
214+
- **Unit Tests** - Component-level functionality validation
215+
- **Integration Tests** - Inter-component communication testing
216+
- **End-to-End Tests** - Complete IRC network functionality
217+
- **Load Tests** - Performance and stability under realistic usage
218+
- **Security Tests** - Vulnerability and penetration testing
219+
220+
### Code Style
221+
222+
- Simple, clean, maintainable solutions preferred
223+
- Match existing code style and formatting
224+
- Preserve comments and documentation
225+
- Use descriptive, evergreen naming conventions
226+
- No mock implementations - always use real data and APIs
227+
228+
## Documentation
229+
230+
### Key Files
231+
232+
- **`README.md`** - This comprehensive project overview
233+
- **`LICENSE`** - MIT License for the project
234+
235+
### Additional Resources
236+
237+
- [Fly.io Documentation](https://fly.io/docs/)
238+
- [Tailscale Documentation](https://tailscale.com/kb/)
239+
- [Solanum IRCd Documentation](https://github.com/solanum-ircd/solanum)
240+
- [Atheme Services Documentation](https://github.com/atheme/atheme)
241+
242+
## License
243+
244+
This project is licensed under the MIT License - see the
245+
[LICENSE](/Users/perigrin/dev/magnet/LICENSE) file for details.
246+
247+
## Organizations
248+
249+
- **Fly.io Organization**: `magnet-irc`
250+
- **Tailscale Organization**: `perl-irc`
251+
- **Github Organization**: `perl-irc`
252+
253+
## Support
254+
255+
For issues, questions, or contributions:
256+
1. Submit issues following the established format
257+
2. Ensure all tests pass before requesting reviews
258+
259+
---
260+
261+
**Note**: This infrastructure is designed for production IRC network operation.
262+
Follow all security best practices and test thoroughly in development
263+
environments before production deployment.

0 commit comments

Comments
 (0)