Fly.io Hello World
Overview
Deploy a minimal app to Fly.io using fly launch. Fly.io runs Docker containers on Firecracker microVMs across 30+ regions worldwide. Two paths: flyctl CLI (simple) or Machines API (programmatic).
Instructions
Step 1: Launch with flyctl
mkdir fly-hello && cd fly-hello
cat > Dockerfile << 'EOF'
FROM node:20-alpine
WORKDIR /app
COPY server.js .
EXPOSE 3000
CMD ["node", "server.js"]
EOF
cat > server.js << 'EOF'
const http = require('http');
const server = http.createServer((req, res) => {
res.writeHead(200, { 'Content-Type': 'application/json' });
res.end(JSON.stringify({
message: 'Hello from Fly.io!',
region: process.env.FLY_REGION,
app: process.env.FLY_APP_NAME,
}));
});
server.listen(3000, () => console.log('Listening on :3000'));
EOF
fly launch --name hello-fly --region iad --now
Step 2: Verify Deployment
fly status
fly open
fly logs
curl https://hello-fly.fly.dev/
Step 3: Deploy via Machines API
const FLY_API = 'https://api.machines.dev';
const headers = {
'Authorization': `Bearer ${process.env.FLY_API_TOKEN}`,
'Content-Type': 'application/json',
};
const app = await fetch(`${FLY_API}/v1/apps`, {
method: 'POST',
headers,
body: JSON.stringify({
app_name: 'hello-api',
org_slug: 'personal',
}),
}).then(r => r.json());
const machine = await fetch(`${FLY_API}/v1/apps/hello-api/machines`, {
method: 'POST',
headers,
body: JSON.stringify({
region: 'iad',
config: {
image: 'nginx:alpine',
services: [{
ports: [{ port: 443, handlers: ['tls', 'http'] }],
protocol: 'tcp',
internal_port: 80,
}],
guest: { cpu_kind: 'shared', cpus: 1, memory_mb: 256 },
},
}),
}).then(r => r.json());
console.log(`Machine ${machine.id} created in ${machine.region}`);
Output
Machine e784079f004d86 created in iad
App URL: https://hello-api.fly.dev
Error Handling
| Error | Cause | Solution |
|---|
No machines in group | App exists but no machines | Run fly deploy or create via API |
Could not find image | Docker build failed | Check Dockerfile, run docker build . locally |
Region not available | Invalid region code | Use fly platform regions to list valid codes |
Insufficient resources | Org quota reached | Check fly orgs show or upgrade plan |
Resources
Next Steps
Proceed to flyio-local-dev-loop for development workflow setup.
