{"_id":"@ainative/skill-railway-deployment","name":"@ainative/skill-railway-deployment","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@ainative/skill-railway-deployment","version":"1.0.0","description":"Railway deployment workflows, nixpacks configuration, environment management, and production troubleshooting","main":"SKILL.md","keywords":["railway","deployment","nixpacks","devops","production","ci-cd","infrastructure","platform-as-a-service","ainative","skill"],"author":{"name":"AINative Studio"},"license":"MIT","homepage":"https://ainative.studio/skills/railway-deployment","repository":{"type":"git","url":"git+https://github.com/AINative-Studio/ainative-skills.git","directory":"skills/railway-deployment"},"bugs":{"url":"https://github.com/AINative-Studio/ainative-skills/issues"},"engines":{"node":">=18.0.0"},"publishConfig":{"access":"public"},"ainative":{"skill":{"name":"railway-deployment","version":"1.0.0","type":"deployment","capabilities":["nixpacks-configuration","environment-management","deployment-troubleshooting","production-readiness","rollback-procedures"],"tags":["railway","deployment","nixpacks","devops","production"]}},"scripts":{"validate":"node -e \"require('fs').readFileSync('SKILL.md', 'utf8')\"","test":"npm run validate"},"_id":"@ainative/skill-railway-deployment@1.0.0","gitHead":"6b796cac1c2fb43072eca570f442dd40a55c8cd9","_nodeVersion":"22.21.0","_npmVersion":"10.9.4","dist":{"integrity":"sha512-22YQLZbs+SbzYZHMr53LoDY6k2fE6wPCZ2CzkLDB5yKRhSRHdAwJnZB1UKojYjvBLCsTwi33o0v14KwTf3faug==","shasum":"067a663b73b19cb0cac38b554b651cd01d342b3c","tarball":"https://registry.npmjs.org/@ainative/skill-railway-deployment/-/skill-railway-deployment-1.0.0.tgz","fileCount":7,"unpackedSize":70799,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIB1NbucPKGBNLSg7XWGKjdycOxcaH4LV+hypLBYRS0oMAiA5T1q96WltieXI9Pjoh9abZ5SyaoXbLK44PjaP/3WyWw=="}]},"_npmUser":{"name":"ainative-studio","email":"toby@rely.ventures"},"directories":{},"maintainers":[{"name":"ainative-studio","email":"toby@rely.ventures"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/skill-railway-deployment_1.0.0_1767773573911_0.6320424007257628"},"_hasShrinkwrap":false}},"time":{"created":"2026-01-07T08:12:53.822Z","1.0.0":"2026-01-07T08:12:54.063Z","modified":"2026-01-07T08:12:54.654Z"},"maintainers":[{"name":"ainative-studio","email":"toby@rely.ventures"}],"description":"Railway deployment workflows, nixpacks configuration, environment management, and production troubleshooting","homepage":"https://ainative.studio/skills/railway-deployment","keywords":["railway","deployment","nixpacks","devops","production","ci-cd","infrastructure","platform-as-a-service","ainative","skill"],"repository":{"type":"git","url":"git+https://github.com/AINative-Studio/ainative-skills.git","directory":"skills/railway-deployment"},"author":{"name":"AINative Studio"},"bugs":{"url":"https://github.com/AINative-Studio/ainative-skills/issues"},"license":"MIT","readme":"# Railway Deployment Skill\n\nOfficial AINative Studio skill for Railway deployment workflows, nixpacks configuration, environment management, and production troubleshooting.\n\n## Overview\n\nThis skill provides comprehensive guidance for deploying applications to Railway, including build configuration, environment variable management, troubleshooting, and production deployment best practices.\n\n## Installation\n\n### Using AINative Studio CLI\n\n```bash\nainative skill install @ainative/skill-railway-deployment\n```\n\n### Manual Installation\n\n1. Clone or download this skill directory\n2. Place it in your AINative Studio skills folder:\n   ```bash\n   cp -r railway-deployment ~/.ainative/skills/\n   ```\n\n## When to Use This Skill\n\nUse this skill when you need help with:\n\n- Deploying applications to Railway platform\n- Configuring nixpacks.toml for custom builds\n- Managing environment variables across services\n- Debugging deployment failures\n- Setting up multi-service Railway projects\n- Troubleshooting production issues\n- Configuring database migrations on Railway\n- Setting up health checks and monitoring\n\n## Quick Start\n\n### Basic Python Deployment\n\nCreate `nixpacks.toml` in your project root:\n\n```toml\n[phases.setup]\nnixPkgs = ['python310', 'postgresql']\nnixLibs = ['libpq']\n\n[phases.install]\ncmds = ['pip install -r requirements.txt']\n\n[start]\ncmd = 'uvicorn main:app --host 0.0.0.0 --port $PORT'\n```\n\nConfigure environment variables:\n```bash\nrailway variables set DATABASE_URL=${{Postgres.DATABASE_URL}}\nrailway variables set ENVIRONMENT=production\nrailway variables set DEBUG=false\n```\n\nDeploy:\n```bash\nrailway up\n```\n\n### Basic Node.js Deployment\n\nCreate `nixpacks.toml`:\n\n```toml\n[phases.setup]\nnixPkgs = ['nodejs-18_x']\n\n[phases.install]\ncmds = ['npm ci']\n\n[phases.build]\ncmds = ['npm run build']\n\n[start]\ncmd = 'node dist/index.js'\n```\n\nDeploy:\n```bash\nrailway up\n```\n\n## Skill Contents\n\n### Main Documentation\n\n- **SKILL.md** - Complete skill guide with:\n  - Core deployment principles\n  - Common workflows\n  - nixpacks configuration patterns\n  - Environment variable management\n  - Troubleshooting guide\n  - Best practices\n\n### Reference Documentation\n\n- **nixpacks-config.md** - Comprehensive nixpacks configuration patterns\n  - Language-specific configurations (Python, Node.js, etc.)\n  - Common system dependencies\n  - Multi-stage builds\n  - Caching strategies\n  - Version compatibility\n\n- **env-management.md** - Environment variable management\n  - Railway variable types\n  - Database configuration\n  - Service-to-service communication\n  - Secret management\n  - External API integration\n  - Validation and defaults\n\n- **troubleshooting.md** - Common deployment issues and solutions\n  - Build failures\n  - Runtime failures\n  - Database connection issues\n  - CORS errors\n  - Performance issues\n  - Rollback procedures\n\n- **production-checklist.md** - Complete deployment checklist\n  - Pre-deployment verification\n  - Deployment process\n  - Post-deployment monitoring\n  - Security audit\n  - Rollback procedures\n\n## Common Use Cases\n\n### Multi-Service Deployment\n\nDeploy frontend and backend separately with service references:\n\n**Backend (FastAPI):**\n```bash\n# Environment variables\nCORS_ORIGINS=https://${{frontend.RAILWAY_PUBLIC_DOMAIN}}\nDATABASE_URL=${{Postgres.DATABASE_URL}}\n```\n\n**Frontend (React):**\n```bash\n# Environment variables\nVITE_API_URL=https://${{backend.RAILWAY_PUBLIC_DOMAIN}}\n```\n\n### Database Migration on Deploy\n\n```toml\n[phases.build]\ncmds = [\n  'pip install -r requirements.txt',\n  'alembic upgrade head'\n]\n```\n\n### Production-Ready Configuration\n\n```toml\n[phases.setup]\nnixPkgs = ['python310', 'postgresql']\nnixLibs = ['libpq']\n\n[phases.install]\ncmds = [\n  'pip install --upgrade pip',\n  'pip install -r requirements.txt'\n]\n\n[phases.build]\ncmds = [\n  'alembic upgrade head',\n  'python -m compileall .'\n]\n\n[start]\ncmd = 'gunicorn main:app --workers 4 --worker-class uvicorn.workers.UvicornWorker --bind 0.0.0.0:$PORT --timeout 120'\n```\n\n## Key Concepts\n\n### nixpacks Build Phases\n\n1. **Setup** - Install system packages\n2. **Install** - Install application dependencies\n3. **Build** - Build application (compile, bundle, etc.)\n4. **Start** - Command to start the application\n\n### Railway Environment Variables\n\n- **Service References**: `${{ServiceName.VARIABLE}}`\n- **Railway Secrets**: Encrypted storage for sensitive data\n- **System Variables**: `PORT`, `RAILWAY_ENVIRONMENT`, `RAILWAY_PUBLIC_DOMAIN`\n\n### Health Checks\n\nAlways implement a health check endpoint:\n\n```python\n@app.get(\"/health\")\nasync def health_check():\n    return {\"status\": \"healthy\"}\n```\n\n### Port Binding\n\nAlways bind to Railway's PORT variable and 0.0.0.0:\n\n```python\nimport os\nport = int(os.environ.get('PORT', 8000))\nuvicorn.run(app, host='0.0.0.0', port=port)\n```\n\n## Troubleshooting Quick Reference\n\n### Build Failed\n1. Check nixpacks.toml syntax\n2. Verify all nixPkgs are spelled correctly\n3. Review build logs: `railway logs | grep build`\n\n### Application Not Responding\n1. Verify binding to `0.0.0.0:$PORT`\n2. Check health endpoint exists\n3. Review application logs: `railway logs`\n\n### Database Connection Failed\n1. Verify DATABASE_URL is set: `railway variables`\n2. Check database service is running\n3. Use private URL for better performance\n\n### Environment Variable Not Found\n1. List all variables: `railway variables`\n2. Redeploy to pick up changes: `railway up`\n\n## Railway CLI Reference\n\n```bash\n# Login and setup\nrailway login\nrailway link\n\n# Deployment\nrailway up                    # Deploy current directory\nrailway up --detach          # Deploy without streaming logs\n\n# Environment management\nrailway variables            # List all variables\nrailway variables set KEY=value\nrailway variables delete KEY\n\n# Debugging\nrailway logs                 # View logs\nrailway logs --follow        # Stream logs\nrailway run <command>        # Run command in deployment\nrailway shell               # Open shell\n\n# Service management\nrailway status              # Check service status\nrailway domain             # Manage custom domains\n```\n\n## Best Practices\n\n1. **Always test locally** with nixpacks before deploying\n2. **Use Railway secrets** for sensitive data\n3. **Implement health checks** for monitoring\n4. **Use private domains** for service-to-service communication\n5. **Enable logging** for debugging and monitoring\n6. **Document environment variables** in `.env.example`\n7. **Test migrations** before running in production\n8. **Implement rollback procedures** for critical deployments\n\n## Examples\n\n### FastAPI + PostgreSQL + Redis\n\n```toml\n[phases.setup]\nnixPkgs = ['python310', 'postgresql']\nnixLibs = ['libpq']\n\n[phases.install]\ncmds = ['pip install -r requirements.txt']\n\n[phases.build]\ncmds = ['alembic upgrade head']\n\n[start]\ncmd = 'uvicorn main:app --host 0.0.0.0 --port $PORT --workers 4'\n```\n\nEnvironment:\n```bash\nDATABASE_URL=${{Postgres.DATABASE_URL}}\nREDIS_URL=${{Redis.REDIS_URL}}\nJWT_SECRET=${{secrets.JWT_SECRET}}\nCORS_ORIGINS=https://${{frontend.RAILWAY_PUBLIC_DOMAIN}}\n```\n\n### Next.js Full-Stack\n\n```toml\n[phases.setup]\nnixPkgs = ['nodejs-18_x']\n\n[phases.install]\ncmds = ['npm ci']\n\n[phases.build]\ncmds = ['npm run build']\n\n[start]\ncmd = 'npm start'\n```\n\nEnvironment:\n```bash\nDATABASE_URL=${{Postgres.DATABASE_URL}}\nNEXTAUTH_URL=https://${{RAILWAY_PUBLIC_DOMAIN}}\nNEXTAUTH_SECRET=${{secrets.NEXTAUTH_SECRET}}\n```\n\n## Contributing\n\nFound an issue or have a suggestion? Please contribute:\n\n1. Open an issue with deployment scenario\n2. Submit pull request with improvements\n3. Share your Railway configuration patterns\n\n## Support\n\n- Railway Documentation: https://docs.railway.app\n- Railway Discord: https://discord.gg/railway\n- AINative Studio Discord: [Your Discord link]\n\n## License\n\nMIT License - see LICENSE file for details\n\n## Version History\n\n### 1.0.0 (2026-01-03)\n- Initial release\n- Complete nixpacks configuration guide\n- Environment variable management patterns\n- Comprehensive troubleshooting guide\n- Production deployment checklist\n- Railway CLI reference\n- Multi-service deployment examples\n\n## Related Skills\n\n- `@ainative/skill-postgresql-data-modeling` - Database design and optimization\n- `@ainative/skill-fastapi-development` - FastAPI application development\n- `@ainative/skill-github-oauth` - OAuth integration patterns\n\n## Acknowledgments\n\nBuilt with expertise from real-world Railway deployments and best practices from the Railway community.\n","readmeFilename":"README.md","_rev":"1-5434671c2dff18b047d4cdd901b0ed7b"}