Novo Projeto / Serviço / Banco de Dados

Criar projetos, serviços e bancos de dados no Railway com configuração adequada.

Quando Usar

Usuário diz "deploy to railway" (adicionar serviço se vinculado, inicializar se não)
Usuário diz "create a railway project", "init", "new project" (novo projeto explícito)
Usuário diz "link to railway", "connect to railway"
Usuário diz "create a service", "add a backend", "new api service"
Usuário diz "create a vite app", "create a react website", "make a python api"
Usuário diz "deploy from github.com/user/repo", "create service from this repo"
Usuário diz "add postgres", "add a database", "add redis", "add mysql", "add mongo"
Usuário diz "connect to postgres", "wire up the database", "connect my api to redis"
Usuário diz "add postgres and connect to the server"
Configurando código + serviço Railway juntos

Pré-requisitos

Verificar CLI instalado:

command -v railway

Se não estiver instalado:

Instale Railway CLI:

npm install -g @railway/cli

brew install railway

Verificar autenticação:

railway whoami --json

Se não autenticado:

Execute railway login para autenticar.

Fluxo de Decisão

railway status --json (no diretório atual)
     │
┌────┴────┐
Vinculado Não vinculado
  │            │
  │       Verificar pai: cd .. && railway status --json
  │            │
  │       ┌────┴────┐
  │    Pai         Não vinculado
  │    Vinculado   em nenhum lugar
  │       │            │
  │   Adicionar     railway list
  │   serviço          │
  │   Definir       ┌───┴───┐
  │   rootDir    Corresponde?  Sem correspondência
  │   Deploy           │        │
  │       │        Vincular   Inicializar novo
  └───────┴────────┴────────┘
           │
    Usuário quer serviço?
           │
     ┌─────┴─────┐
    Sim         Não
     │           │
Gerar código   Pronto
     │
railway add --service
     │
Configurar se necessário
     │
Pronto para deploy

Verificar Estado Atual

railway status --json

Se vinculado: Adicionar um serviço ao projeto existente (veja abaixo)
Se não vinculado: Verificar se um diretório PAI está vinculado (veja abaixo)

Quando Já Vinculado

Comportamento padrão: "deploy to railway" = adicionar um serviço ao projeto vinculado.

NÃO criar um novo projeto a menos que o usuário DIGA EXPLICITAMENTE:

"new project", "create a project", "init a project"
"separate project", "different project"

Nomes de aplicativos como "flappy-bird" ou "my-api" são nomes de SERVIÇOS, não de projetos.

Usuário: "create a vite app called foo and deploy to railway"
Projeto: Já vinculado a "my-project"

ERRADO: railway init -n foo
CORRETO: railway add --service foo

Vinculação de Diretório Pai

Railway CLI percorre a árvore de diretórios para encontrar um projeto vinculado. Se você estiver em um subdiretório:

cd .. && railway status --json

Se o pai estiver vinculado, você não precisa inicializar/vincular o subdiretório. Em vez disso:

Criar serviço: railway add --service <name>
Definir rootDirectory para o caminho do subdiretório via skill de ambiente
Deploy a partir da raiz: railway up

Se nenhum pai estiver vinculado, prossiga com o fluxo de inicialização ou vinculação.

Decisão Init vs Link

Pule esta seção se já estiver vinculado - apenas adicione um serviço em vez disso.

Use esta seção apenas quando NENHUM projeto estiver vinculado (diretamente ou via pai).

Verificar Projetos do Usuário

A saída pode ser grande. Execute em um subaagent e extraia apenas:

id e name do projeto
id e name do workspace

railway list --json

Lógica de Decisão

Usuário diz explicitamente "new project" → Use railway init
Usuário nomeia um projeto existente → Use railway link
Nome do diretório corresponde a um projeto existente → Pergunte: vincular existente ou criar novo?
Nenhum projeto correspondente → Use railway init
Ambíguo → Pergunte ao usuário

Criar Novo Projeto

railway init -n <name>

Opções:

-n, --name - Nome do projeto (auto-gerado se omitido em modo não-interativo)
-w, --workspace - Nome ou ID do workspace (obrigatório se existirem múltiplos workspaces)

Múltiplos Workspaces

Se o usuário tiver múltiplos workspaces, railway init exigirá a flag --workspace.

Obtenha IDs de workspace de:

railway whoami --json

O array workspaces contém { id, name } para cada workspace.

Inferindo workspace da entrada do usuário: Se o usuário disser "deploy into xxx workspace" ou "create project in my-team", combine o nome com o array de workspaces e use o ID correspondente:

# Usuário diz: "create a project in my personal workspace"
railway whoami --json | jq '.workspaces[] | select(.name | test("personal"; "i"))'
# Use o ID correspondente: railway init -n myapp --workspace <matched-id>

Vincular Projeto Existente

railway link -p <project>

Opções:

-p, --project - Nome ou ID do projeto
-e, --environment - Ambiente (padrão: production)
-s, --service - Serviço a vincular
-t, --team - Team/workspace

Criar Serviço

Após o projeto estar vinculado, crie um serviço:

railway add --service <name>

Para fontes de repositório GitHub: Criar um serviço vazio, então invocar a skill railway-environment para configurar a fonte via staged changes API. NÃO use railway add --repo - requer integração com app GitHub que frequentemente falha.

Fluxo:

railway add --service my-api
Invocar skill railway-environment para definir source.repo e source.branch
Aplicar mudanças para disparar o deploy

Configurar Baseado no Tipo de Projeto

Consulte railpack.md para configuração de build. Consulte monorepo.md para padrões de monorepo.

Site estático (Vite, CRA, Astro static):

Railpack auto-detecta diretórios de saída comuns (dist, build)
Se diretório de saída não-padrão: invocar skill railway-environment para definir RAILPACK_STATIC_FILE_ROOT
NÃO use CLI railway variables - sempre use a skill de ambiente

Node.js SSR (Next.js, Nuxt, Express):

Verificar se existe script start em package.json
Se start customizado necessário: invocar skill railway-environment para definir startCommand

Python (FastAPI, Django, Flask):

Verificar se existe requirements.txt ou pyproject.toml
Auto-detectado por Railpack, geralmente sem config necessária

Go:

Verificar se existe go.mod
Auto-detectado, sem config necessária

Configuração de Monorepo

Decisão crítica: Diretório raiz vs comandos customizados.

Monorepo isolado (aplicativos não compartilham código):

Definir Root Directory para o subdiretório do aplicativo (ex: /frontend)
Apenas o código desse diretório está disponível durante o build

Monorepo compartilhado (workspaces TypeScript, pacotes compartilhados):

NÃO definir diretório raiz
Definir comandos de build/start customizados para filtrar o pacote:
- pnpm: pnpm --filter <package> build
- npm: npm run build --workspace=packages/<package>
- yarn: yarn workspace <package> build
- Turborepo: turbo run build --filter=<package>
Definir watch paths para prevenir rebuilds desnecessários

Veja monorepo.md para padrões detalhados.

Orientação de Setup de Projeto

Analisar a base de código para garantir compatibilidade com Railway.

Analisar Base de Código

Verificar arquivos de projeto existentes:

package.json → Projeto Node.js
requirements.txt, pyproject.toml → Projeto Python
go.mod → Projeto Go
Cargo.toml → Projeto Rust
index.html → Site estático
Nenhum → Guiar geração de scaffold

Detecção de monorepo:

pnpm-workspace.yaml → pnpm workspace (monorepo compartilhado)
package.json com campo workspaces → npm/yarn workspace (monorepo compartilhado)
turbo.json → Turborepo (monorepo compartilhado)
Múltiplos subdiretórios com package.json separados mas sem config de workspace → monorepo isolado

Dicas de Scaffolding

Se não houver código, sugerir padrões mínimos de railpack.md:

Site estático:

Criar um arquivo index.html no diretório raiz.

Vite React:

npm create vite@latest . -- --template react

Astro:

npm create astro@latest

Python FastAPI:

Criar main.py com aplicativo FastAPI e requirements.txt com dependências.

Go:

Criar main.go com servidor HTTP ouvindo na variável de ambiente PORT.

Bancos de Dados

Para adicionar bancos de dados (Postgres, Redis, MySQL, MongoDB), use a skill railway-railway-database.

A skill railway-railway-database gerencia:

Criação de serviços de banco de dados
Referências de variáveis de conexão
Vinculação de serviços a bancos de dados

Composabilidade

Após serviço criado: Use skill railway-deploy para fazer push de código
Para config avançada: Use skill railway-environment (buildCommand, startCommand)
Para domínios: Use skill railway-domain
Para verificações de status: Use skill railway-status
Para operações de serviço (renomear, deletar, status): Use skill railway-service

Tratamento de Erros

CLI Não Instalado

Railway CLI não instalado. Instale com:
  npm install -g @railway/cli
ou
  brew install railway

Não Autenticado

Não logado no Railway. Execute: railway login

Nenhum Workspace

Nenhum workspace encontrado. Crie um em railway.com ou verifique autenticação.

Nome de Projeto Já Existe

Nome de projeto já existe. Você pode:
- Vincular ao existente: railway link -p <name>
- Usar nome diferente: railway init -n <other-name>

Nome de Serviço Já Existe

Nome de serviço já existe neste projeto. Use um nome diferente:
  railway add --service <other-name>

Exemplos

Criar Site Estático HTML

Usuário: "create a simple html site and deploy to railway"

1. Verificar status → não vinculado
2. railway init -n my-site
3. Guiar: criar index.html
4. railway add --service my-site
5. Nenhuma config necessária (index.html na raiz auto-detectado)
6. Usar skill deploy: railway up
7. Usar skill domain para URL pública

Criar Serviço Vite React

Usuário: "create a vite react service"

1. Verificar status → vinculado (ou inicializar/vincular primeiro)
2. Scaffold: npm create vite@latest frontend -- --template react
3. railway add --service frontend
4. Nenhuma config necessária (saída Vite dist auto-detectada)
5. Usar skill deploy: railway up

Adicionar API Python ao Projeto

Usuário: "add a python api to my project"

1. Verificar status → vinculado
2. Guiar: criar main.py com FastAPI, requirements.txt
3. railway add --service api
4. Nenhuma config necessária (FastAPI auto-detectado)
5. Usar skill deploy

Vincular e Adicionar Serviço

Usuário: "connect to my backend project and add a worker service"

1. railway list --json → encontrar "backend"
2. railway link -p backend
3. railway add --service worker
4. Guiar setup baseado no tipo de worker

Deploy para Railway (Ambíguo)

Usuário: "deploy to railway"

1. railway status → não vinculado
2. railway list → tem projetos
3. Diretório é "my-app", encontrou projeto "my-app"
4. Perguntar: "Encontrei projeto existente 'my-app'. Vincular a ele ou criar novo?"
5. Usuário: "link"
6. railway link -p my-app
7. Perguntar: "Criar um serviço para este código?"

Adicionar Serviço a Monorepo Isolado

Usuário: "create a static site in the frontend directory"

1. Verificar: /frontend tem seu próprio package.json, nenhuma config de workspace
2. Este é monorepo isolado → usar diretório raiz
3. railway add --service frontend
4. Invocar skill de ambiente para definir rootDirectory: /frontend
5. Definir watch paths: /frontend/**

Adicionar Serviço a Monorepo TypeScript

Usuário: "add a new api package to this turborepo"

1. Verificar: turbo.json existe, pnpm-workspace.yaml existe
2. Este é monorepo compartilhado → usar comandos customizados, NÃO diretório raiz
3. Guiar: criar packages/api com package.json
4. railway add --service api
5. Invocar skill de ambiente para definir buildCommand e startCommand (NÃO definir rootDirectory)
6. Definir watch paths: /packages/api/**, /packages/shared/**

Deploy de Pacote Existente de Workspace pnpm

Usuário: "deploy the backend package to railway"

1. Verificar: pnpm-workspace.yaml existe → monorepo compartilhado
2. railway add --service backend
3. Invocar skill de ambiente para definir buildCommand e startCommand
4. Definir watch paths para backend + deps compartilhadas

Deploy de Subdiretório de Projeto Vinculado

Usuário: "create a vite app in my-app directory and deploy to railway"
CWD: ~/projects/my-project/my-app (pai já vinculado a "my-project")

1. Verificar status em my-app → não vinculado
2. Verificar pai: cd .. && railway status → ESTÁ vinculado a "my-project"
3. NÃO inicializar/vincular o subdiretório
4. Scaffold: bun create vite my-app --template react-ts
5. cd my-app && bun install
6. railway add --service my-app
7. Invocar skill de ambiente para definir rootDirectory: /my-app
8. Deploy a partir da raiz: railway up