A production-ready .NET Core Web API configured for deployment on Convox.
.NET Core is Microsoft's free, open-source, and cross-platform framework for building modern cloud-based applications. This example demonstrates how to deploy a .NET Core Web API on Convox with automatic SSL, load balancing, and zero-downtime deployments.
Deploy to Convox Cloud for a fully-managed platform experience, or to your own Convox Rack for complete control over your infrastructure. Either way, you'll get automatic SSL, load balancing, and zero-downtime deployments out of the box.
- RESTful API - Full CRUD operations with a clean REST interface
- Cross-Platform - Runs on Linux, Windows, and macOS
- High Performance - Built on ASP.NET Core's high-performance web server
- Container-Ready - Multi-stage Docker build for optimized images
- Production Configured - Environment-based configuration with secure defaults
- Health Monitoring - Built-in health check endpoint for reliability
- Auto-Scaling Ready - Configured for horizontal scaling based on load
-
Create a Cloud Machine at console.convox.com
-
Create the app:
convox cloud apps create dotnet-api -i your-machine-name- Deploy the app:
convox cloud deploy -a dotnet-api -i your-machine-name- View your app:
convox cloud services -a dotnet-api -i your-machine-nameVisit your URL to access the API!
- Create the app:
convox apps create dotnet-api- Deploy the app:
convox deploy -a dotnet-api- View your app:
convox services -a dotnet-apiVisit your URL to access the API!
The example API includes a HelloController with the following endpoints:
| Method | Endpoint | Description |
|---|---|---|
| GET | / |
Returns "OK" status |
| GET | /api/hello |
Returns a hello message |
| GET | /api/hello/{id} |
Gets a resource by ID |
| POST | /api/hello |
Creates a new message |
| PUT | /api/hello/{id} |
Updates a message |
| PATCH | /api/hello/{id} |
Partially updates a message |
| DELETE | /api/hello/{id} |
Deletes a message |
# Get the service URL
convox services -a dotnet-api
# Test the root endpoint
curl https://web.dotnet-api.cloud.convox.com/
# Test the Hello API
curl https://web.dotnet-api.cloud.convox.com/api/hello
# Get a specific resource
curl https://web.dotnet-api.cloud.convox.com/api/hello/123
# Create a new message
curl -X POST https://web.dotnet-api.cloud.convox.com/api/hello \
-H "Content-Type: application/json" \
-d '"Hello Convox!"'
# Update a message
curl -X PUT https://web.dotnet-api.cloud.convox.com/api/hello/123 \
-H "Content-Type: application/json" \
-d '"Updated message"'Configure your application using environment variables:
convox env set \
ASPNETCORE_ENVIRONMENT=Production \
ConnectionStrings__DefaultConnection=your-connection-string \
-a dotnet-apiAdjust the number of running processes and resources:
# Scale to 3 instances with specific resources
convox scale web --count 3 --cpu 512 --memory 1024 -a dotnet-apiOr configure autoscaling in your convox.yml:
services:
web:
build: .
port: 5000
scale:
count: 1-5
cpu: 256
memory: 512
targets:
cpu: 70
memory: 80- Install .NET SDK:
# macOS
brew install dotnet
# Ubuntu/Debian
sudo apt-get install dotnet-sdk-9.0
# Windows
# Download from https://dotnet.microsoft.com/download- Run locally:
dotnet restore
dotnet runThe API will be available at http://localhost:5178
Use Convox to run the application locally with Docker:
convox startThis will build and run the application in a local Docker environment that mimics production.
.
├── Controllers/
│ └── HelloController.cs # Main API controller
├── Properties/
│ └── launchSettings.json # Local development settings
├── Dockerfile # Multi-stage Docker build
├── DotNetCore.csproj # Project configuration
├── DotNetCore.sln # Solution file
├── Program.cs # Application entry point
├── appsettings.json # Production configuration
├── appsettings.Development.json # Development configuration
└── convox.yml # Convox deployment configuration
The application uses a multi-stage Docker build for optimal image size:
- Build Stage: Uses the .NET SDK to compile the application
- Runtime Stage: Uses the lighter ASP.NET runtime image
This results in smaller, more secure production images.
Cloud:
convox cloud logs -a dotnet-api -i your-machine-nameRack:
convox logs -a dotnet-apiThe application responds to health checks at the root endpoint:
curl https://your-dotnet-api-url/- Use Environment Variables: Never hardcode secrets or configuration
- Enable HTTPS: Always use HTTPS in production (Convox handles this automatically)
- Set Resource Limits: Configure appropriate CPU and memory limits
- Use Health Checks: Ensure your application can be monitored
- Multi-Stage Builds: Keep your Docker images small and secure
- Regular Updates: Keep .NET Core and dependencies updated
Check that the PORT environment variable is being read:
convox logs -a dotnet-api --filter "Now listening"Verify environment variables:
convox env -a dotnet-apiIf the build fails, check the build logs:
convox builds logs BUILD_ID -a dotnet-apiCommon issues:
- Ensure Dockerfile references the correct .NET version
- Check that all required files are included in the build context
- Verify NuGet package sources are accessible
Monitor resource usage:
convox ps -a dotnet-apiConsider scaling up if CPU or memory usage is high:
convox scale web --cpu 1000 --memory 2048 -a dotnet-apiAdd your custom domain:
convox services -a dotnet-api
# Note the router domain, then create a CNAME to itTo add a PostgreSQL database:
- Update your
convox.yml:
resources:
database:
type: postgres
options:
storage: 10
version: 13
services:
web:
build: .
port: 5000
resources:
- database- Access the database URL in your application:
var connectionString = Environment.GetEnvironmentVariable("DATABASE_URL");Add a worker service to your convox.yml:
services:
web:
build: .
port: 5000
worker:
build: .
command: dotnet YourApp.dll --worker
scale:
count: 1
cpu: 256
memory: 512- .NET Community: dotnet.microsoft.com/platform/community
- Convox Support: cloud-support@convox.com
- GitHub Issues: Create an issue