https://github.com/mac9sb/server
https://github.com/mac9sb/server
Last synced: 5 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/mac9sb/server
- Owner: mac9sb
- Created: 2026-01-23T16:06:35.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-01-26T04:03:57.000Z (5 months ago)
- Last Synced: 2026-01-26T09:16:51.254Z (5 months ago)
- Language: Pkl
- Size: 10.7 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Developer Server
An arc project for hosting applications and static sites.
## Directory Structure
### `sites/`
All hosted applications and static sites. This unified directory contains both dynamic server applications and static site generators.
#### Server Applications
Server applications built with Swift and Hummingbird. Each subdirectory contains a `Web/` directory with its own `Package.swift`.
**Working with apps:**
```sh
cd sites//Web
swift build -c release
```
Apps are configured in `Arc.swift` with `.service()` and require a port assignment.
#### Static Sites
Static sites built with Swift and WebUI. Each subdirectory is a standalone site generator with its own `Package.swift`.
**Working with static sites:**
```sh
cd sites/
swift run
```
This generates the site into a `.output` directory. Sites are configured in `Arc.swift` with `.page()`.
### `tooling/`
Shared tooling and utilities used across projects:
- **arc** - Server orchestration and proxy
- **web-ui** - HTML generation framework
- **fluent-gen** - Fluent ORM macro package
- **list** - Enhanced `ls` command-line tool
### `Arc.swift`
Arc server configuration defining all hosted sites and services. This file uses the ArcDescription DSL to configure routing, domains, and process management.
### `config.pkl`
Legacy Pkl configuration (deprecated in favor of `Arc.swift`).
## Running the Server
```sh
arc run # Start in foreground
arc run --background # Start in background
arc status # Check running processes and site health
arc status # View detailed status for a specific project
arc logs # View logs
arc stop # Stop running servers
```
The server proxies requests based on domain configuration in `Arc.swift`.
## Development Workflows
### Command Line
#### Build All Projects
```sh
./scripts/build-all.sh
```
This builds all tooling and sites in the correct dependency order.
#### Build Individual Projects
```sh
# Build Arc
cd tooling/arc && swift build -c release
# Build WebUI
cd tooling/web-ui && swift build -c release
# Build Guest List
cd sites/guest-list/Web && swift build -c release
# Generate Portfolio
cd sites/portfolio && swift run
```
#### Run Tests
```sh
# Test Arc
cd tooling/arc && swift test
# Test WebUI
cd tooling/web-ui && swift test
# Test Guest List
cd sites/guest-list/Web && swift test
```
### Xcode Development
This monorepo includes a unified Xcode workspace for IDE-based development.
#### Open Workspace
```sh
open Developer.xcworkspace
```
**Important:** Always open the workspace, not individual `Package.swift` files.
#### Available Schemes
- **Arc** - Run Arc server in foreground with keep-awake
- **Arc (Background)** - Run Arc in background mode
- **GuestList** - Run Guest List app directly (bypass Arc)
- **Portfolio (Generate)** - Generate portfolio static site
- **WebUI CLI** - Test WebUI command-line interface
Each scheme is pre-configured with the correct working directory and arguments.
#### Quick Start
1. Open `Developer.xcworkspace`
2. Select "Arc" scheme from scheme picker
3. Press `⌘R` to run
4. Arc starts all configured sites
5. Check Xcode console for output
For detailed Xcode setup, debugging tips, and scheme documentation, see [docs/XCODE_SETUP.md](docs/XCODE_SETUP.md).
## File Watching
Arc automatically watches for changes and reloads as needed:
- **Config changes** - Modifications to `Arc.swift` trigger a full configuration reload
- **App binaries** - Rebuilt executables in `sites/` are detected and the corresponding process is restarted
- **Static outputs** - Regenerated `.output` directories in `sites/` are picked up immediately
## Git Submodules
All major components are git submodules:
```sh
# Initialize submodules after clone
git submodule update --init --recursive
# Update all submodules to latest
git submodule update --remote
# Update specific submodule
cd tooling/arc && git pull origin main
```
## Git Hooks (build + test gate)
Install hooks for the root repo and all submodules:
```sh
./scripts/install-githooks.sh
```
Hooks will run validation for the root repo, and `swift format lint`, `swift test`, and `swift build -c release` for every repo with a `Package.swift` before allowing a commit or push.
> [!NOTE]
> Tap hooks are currently disabled.
## Documentation
- [Xcode Setup Guide](docs/XCODE_SETUP.md) - IDE development workflow
- [CLI UX Best Practices](docs/CLI_UX.md) - Command-line interface standards
- [Logging Best Practices](docs/LOGGING.md) - Structured logging guidelines
## Project Standards
### CLI Tools
All command-line tools use [Noora](https://noora.tuist.dev) for consistent terminal output. See [docs/CLI_UX.md](docs/CLI_UX.md) for guidelines.
### Logging
All projects use [swift-log](https://github.com/apple/swift-log) for structured logging. No custom abstractions. See [docs/LOGGING.md](docs/LOGGING.md) for best practices.
### Code Style
- Swift 6.0+ with strict concurrency checking
- Follow Swift API Design Guidelines
- Use SwiftFormat for consistent formatting
- Comprehensive documentation comments
## Architecture
```
Developer/
├── sites/ # All hosted sites
│ ├── guest-list/ # Server application
│ │ └── Web/ # Hummingbird app
│ └── portfolio/ # Static site generator
├── tooling/ # Shared tools
│ ├── arc/ # Server orchestration
│ ├── web-ui/ # HTML generation
│ ├── fluent-gen/ # ORM macros
│ └── list/ # CLI utilities
├── scripts/ # Build and utility scripts
├── docs/ # Documentation
├── Arc.swift # Server configuration
└── Developer.xcworkspace/ # Xcode workspace
```
## Contributing
1. Check out a branch
2. Make changes in appropriate submodule
3. Test locally with `swift test`
4. Format code with `swift format`
5. Commit submodule changes first
6. Update submodule reference in monorepo
7. Push and create PR
## License
See individual projects for license information.