Vapor Deployment and Usage Guide

Prerequisites

Before getting started with Vapor, ensure you have the following installed:

Swift 6.0+ - Vapor requires Swift 6.0 or newer. You can download Swift from swift.org.
macOS or Linux - Vapor supports both macOS and Linux platforms.
Git - For cloning the repository and managing version control.
Xcode (optional) - For development on macOS, Xcode provides a full IDE experience with Swift tools.

Installation

Clone the Repository

git clone https://github.com/vapor/vapor.git
cd vapor

Build and Test

# Build the project
swift build

# Run tests to verify installation
swift test

Install Vapor CLI (Optional)

While not required for the core framework, the Vapor CLI provides helpful tools for project creation and management:

# Install Vapor CLI
swift run vapor --help

Configuration

Vapor uses Swift's native configuration system. Here are the key configuration points:

Server Configuration

The HTTPServer.Configuration struct provides default settings:

// Default configuration
let serverConfig = HTTPServer.Configuration.default(port: 8080)

Key configuration options:

Hostname: Default is 127.0.0.1
Port: Default is 8080
Address: Can be configured as .hostname or .unixDomainSocket

Environment Variables

Vapor supports environment-based configuration through Swift's Environment API. Common environment variables include:

PORT - Override the default port
HOSTNAME - Override the default hostname
LOG_LEVEL - Set logging verbosity

SSL/TLS Configuration

For secure connections, configure SSL using SwiftNIO's NIOSSL:

import NIOSSL

let sslContext = try NIOSSLContext(configuration: .makeClientConfiguration())

Build & Run

Development Server

# Build and run in development mode
swift run Run serve

# Or use the Vapor CLI
vapor run serve

Production Build

# Build for release
swift build -c release

# Run the production binary
.build/release/Run serve

Running Tests

# Run all tests
swift test

# Run specific test suite
swift test --filter ValidationTests

Deployment

Platform Recommendations

Based on Vapor's Swift foundation, these platforms are well-suited:

1. MacStadium (Recommended for Enterprise)

Dedicated macOS servers optimized for Swift applications
Direct Swift toolchain support

2. DigitalOcean App Platform

Supports custom runtimes
Can configure Swift buildpacks

3. AWS Lambda (with Swift Runtime)

Use Swift AWS Lambda runtime
Configure API Gateway for HTTP routing

4. Docker Deployment

FROM swift:6.0

WORKDIR /app
COPY . .
RUN swift build -c release

EXPOSE 8080
CMD [".build/release/Run", "serve"]

Deployment Steps

Build for Production
```
swift build -c release
```

Configure Environment

export PORT=8080
export HOSTNAME=0.0.0.0

Run the Application
```
.build/release/Run serve
```

Troubleshooting

Common Issues and Solutions

1. Swift Version Mismatch

Issue: "error: invalid deployment target for x86_64-apple-macosx10.15" Solution: Ensure Swift 6.0+ is installed and selected

swift --version

2. Port Already in Use

Issue: "Address already in use" Solution: Change the port in configuration

let config = HTTPServer.Configuration.default(port: 8081)

3. File Permissions

Issue: "Permission denied" when accessing files Solution: Check file permissions

chmod +r /path/to/file

4. SSL/TLS Configuration

Issue: "SSL handshake failed" Solution: Verify SSL certificates and configuration

let sslContext = try NIOSSLContext(configuration: .makeServerConfiguration(
    certificateChain: [.certificate(.init(pemFile: "cert.pem"))],
    privateKey: .file("key.pem")
))

5. Dependency Resolution

Issue: "No such module 'Vapor'" Solution: Ensure dependencies are properly resolved

swift package resolve

Getting Help

Documentation: docs.vapor.codes
Community: Join the Discord server
Issues: Report bugs on GitHub Issues

Performance Considerations

Use FileIO for efficient file operations
Implement proper error handling with EventLoopFuture
Leverage Swift's concurrency features for async operations

This guide provides a comprehensive foundation for deploying and using Vapor in production environments. Always refer to the latest documentation for the most up-to-date information.

How to Deploy & Use vapor/vapor