Primeiros passos

Instalando Cipi

Cipi instala uma pilha de produção completa pronta para Laravel em Ubuntu 24.04 ou 26.04 com um único comando. O instalador leva cerca de 10 minutos e configura Nginx, MariaDB, PHP, Valkey (opcional PostgreSQL via cipi db install pgsql após a instalação), Supervisor, Fail2ban, UFW, Certbot, Deployer e o cipi CLI em si.

Do zero à produção em três etapas

# 1 — on a fresh Ubuntu 24.04 / 26.04 VPS, over SSH, as a user with sudo
wget -O - https://cipi.sh/setup.sh | bash

# 2 — create the app (Laravel by default)
cipi app create

# 3 — deploy it and put it behind HTTPS
cipi deploy myapp
cipi ssl install myapp

Esse é todo o caminho. Primeiro crie uma chave SSH no seu computador (abaixo) e execute o instalador no servidor – será solicitado que você cole essa chave pública. Tudo depois disso é explicado em o resto desta página.

Crie uma chave SSH no seu computador

Faça isso no seu laptop ou estação de trabalho, não em VPS. O instalador precisa do público metade da chave para que ele possa bloquear o servidor: após a configuração, você usa SSH como o cipi usuário com esta chave. O login SSH raiz está desativado. Nunca cole o privado chave.

Veja se você já tem um:

ls ~/.ssh/*.pub

Se id_ed25519.pub ou id_rsa.pub está listado, você já tem uma chave - pule geração e copie o arquivo público com o comando abaixo. Se a pasta estiver vazia ou o comando erros, crie uma nova chave Ed25519:

ssh-keygen -t ed25519 -C "you@example.com"

Pressione Enter para aceitar o caminho padrão (~/.ssh/id_ed25519). Defina uma senha se você deseja (recomendado). No macOS e no Linux, execute-o no Terminal; no Windows, use PowerShell ou WSL.

Mostre a chave pública — esta é a única linha que você colará quando o instalador perguntar:

cat ~/.ssh/id_ed25519.pub

Parece ssh-ed25519 AAAA… comment. Copie a linha inteira:

• macOS: pbcopy < ~/.ssh/id_ed25519.pub
• Linux: xclip -sel clip < ~/.ssh/id_ed25519.pub (ou copie do terminais)
• Windows (PowerShell): Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub | Set-Clipboard

Execute o instalador no servidor

SSH no novo Ubuntu VPS como um usuário com sudo, então:

wget -O - https://cipi.sh/setup.sh | bash

O assistente pede a chave pública antes de qualquer pacote ser instalado. Cole a linha você copiou acima (formatos aceitos: ssh-ed25519, ssh-rsa, ecdsa). Cipi limpa comentários, retornos de carro e espaços em branco extras e, em seguida, cria um dedicado cipi Usuário Linux para acesso SSH de administrador e fortalece o SSH: login root desativado, cipi somente chave pública (grupo cipi-ssh), usuários de aplicativos (grupo cipi-apps) pode se conectar com senha. As tentativas de login são limitadas a 3 com um Período de carência de 20 segundos; O encaminhamento X11 está desabilitado.

O instalador também gera um senha raiz aleatória de 40 caracteres, armazena-o em /etc/cipi/server.jsone o exibe no resumo da instalação. É não uma senha SSH: o login SSH root está desabilitado. É o que você digita quando, já logado como cipi usuário com sua chave, você executa su root. Mantenha-o em uma senha gerente.

Instalação não interativa

Para configurações automatizadas, passe sua chave pública SSH por meio do SSH_PUBKEYvariável de ambiente para pular o prompt interativo:

SSH_PUBKEY="ssh-ed25519 AAAA..." wget -O - https://cipi.sh/setup.sh | bash

AWS (login root desabilitado por padrão)

$ ssh ubuntu@your-server-ip
$ sudo -s
$ wget -O - https://cipi.sh/setup.sh | bash

Ao final da instalação você verá uma tela de resumo com os detalhes de acesso SSH, o senha root gerada automaticamente e a senha root MariaDB. Salve-os imediatamente - eles são mostrados apenas uma vez. As credenciais são armazenadas em /etc/cipi/server.json, que — como todos os arquivos de configuração Cipi — é criptografado em repouso usando AES-256-CBC através do built-in Cofre sistema. Credenciais, chaves SSH, .env arquivos e dumps de banco de dados são protegidos tanto em disco e durante a transferência (via Sincronizar arquivos criptografados). Cipi também impõe Retenção de registros compatível com GDPR com políticas de rotação automática para aplicação, segurança e HTTP logs — consulte Retenção de registros para obter detalhes.

Acesso pós-instalação

Após a instalação, acesso de administrador usa autenticação de chave pública como cipi usuário (o login root está desabilitado). Usuários de aplicativos pode usar SSH diretamente com ssh myapp@server-ip e a senha gerada na criação do aplicativo. Para correr cipi comandos ou executar qualquer tarefa administrativa, conecte-se como cipi e então aumente:

# 1. connect to the server (key-based auth only)
$ ssh cipi@your-server-ip

# 2. escalate to root to run cipi commands
cipi@server:~$ sudo -s

# 3. now you can use all cipi commands
root@server:~# cipi status
root@server:~# cipi app list

# 4. to work as an app user, switch with su
root@server:~# su - myapp

Requisitos

• Ubuntu 24.04 ou 26.04 LTS (apenas novas instalações; versões provisórias não são suportadas)
• Acesso root (ou sudo -s na AWS)
• Portas 22, 80 e 443 abertas
• Um servidor limpo — não instale Cipi em um servidor com uma pilha web existente
• A servidor público voltado para a Internet com um roteável IPv4 público endereço — VPS somente NAT, redes domésticas atrás de um roteador e hosts não acessíveis a internet não é suportada
• Virtualização KVM completa ou bare-metal — não OpenVZ, contêineres LXC ou kernel compartilhado ambientes (incluindo Docker local, Docker Desktop, OrbStack, Colima, WSL e similares tempos de execução do contêiner de desktop)

Cipi foi testado e funciona em: DigitalOcean, AWS EC2, Vultr, Linode/Akamai, Hetzner, Google Cloud, OVH, Scaleway e qualquer host KVM ou bare-metal rodando Ubuntu com IP público.

Início rápido

1. Crie seu primeiro aplicativo

O assistente interativo solicita um nome de usuário, domínio primário, URL do repositório Git (formato SSH) e filial quando aplicável, e versão PHP. Laravel aplicativos sempre exigem um repositório; para personalizado apps você pode deixar o repositório vazio para hospedar o site somente via SFTP — vejaaplicativos personalizados. Desde v5.0, Laravel aplicativos podem usar clássico PHP-FPM ou Laravel Octane (FrankenPHP) com --octane - veja Laravel Octane.

$ cipi app create
$ cipi app create --octane   # Laravel Octane (FrankenPHP)

Ou passe todos os sinalizadores diretamente para pular o modo interativo:

$ cipi app create \
    --user=myapp \
    --domain=myapp.com \
    --repository=git@github.com:you/myapp.git \
    --branch=main \
    --php=8.5

No final, Cipi imprime um resumo de credenciais —salve-o, mostrado apenas uma vez - incluindo o endereço IP público do servidor (para configuração DNS), a chave de implantação SSH, credenciais do banco de dados, um pronto para usar mariadb+ssh:// URL de conexão para GUI clientes (TablePlus, DBeaver, Sequel Pro), URL webhook e token webhook.

2. Adicione a chave de implantação ao seu provedor Git

Se você configurou um token GitHub ou GitLab via cipi git, esta etapa é automático — Cipi adiciona a chave de implantação e cria o webhook para você. Veja Configuração automática do Git para obter detalhes.

Caso contrário, copie o ssh-ed25519 ... chave mostrada após a criação do aplicativo e adicione-a como um Implante a chave em seu repositório:

• GitHub: Repositório → Configurações → Chaves de implantação → Adicionar chave de implantação
• GitLab: Repositório → Configurações → Repositório → Implantar chaves

3. Prepare seu projeto Laravel

Cipi usa o driver de banco de dados para cache, sessões e filas. Execute-os uma vez dentro do seu Laravel projete, confirme e envie as migrações geradas:

$ php artisan cache:table
$ php artisan session:table
$ php artisan queue:table
$ php artisan migrate

4. Implantar

$ cipi deploy myapp

O Deployer clona seu repositório em um novo releases/N/ diretório, executa composer install --no-dev, links .env e storage/, corre migrações, corridasartisan optimize, cria storage:link, troca o current link simbólico atomicamente e reinicia os trabalhadores da fila. Tempo de inatividade zero.

5. Instale SSL

$ cipi ssl install myapp

O Certbot provisiona um certificado Let's Encrypt, configura Nginx para HTTPS e atualiza APP_URL em .env. Seu aplicativo Laravel já está ativo https://myapp.com.

Pilha de tecnologia

Cipi traz uma pilha completa e pronta para produção para o seu servidor Ubuntu. Aqui está tudo o que acontece instalado e configurado:

O que cada aplicativo recebe

Cada aplicativo é executado em um ambiente totalmente isolado. Laravel é o padrão – tempo de inatividade zero implanta, seu próprio banco de dados, trabalhadores, agendador e webhook - opcionalmente servido por Octane (FrankenPHP) em vez de PHP-FPM. --custom é para sites simples (WordPress, estático + PHP): uma implantação clássica em htdocs, um docroot configurável, não banco de dados, não .env, sem cron, sem trabalhadores.

Estrutura do aplicativo

Quando você corre cipi app create, Cipi cria um ambiente totalmente isolado para o aplicativo. Aqui está tudo o que é configurado:

/home/myapp/ ← usuário Linux isolado (chmod 750)
├── .ssh/
│   ├── id_ed25519 ← implantar chave (privada)
│   └── id_ed25519.pub ← chave de implantação (pública — adicionada ao Git)
├── .deployer/
│   └── deploy.php ← Configuração do implantador (gerada automaticamente)
├── atual -> releases/3/ ← link simbólico para lançamento ativo
├── releases/
│   ├── 1/
│   ├── 2/
│   └── 3/ ← último lançamento (últimos 5 mantidos)
├── shared/
│   ├── .env ← compilado automaticamente por Cipi
│   └── storage/ ← armazenamento persistente
└── logs/
    ├── nginx-access.log
    ├── nginx-error.log
    ├── php-fpm-error.log
    ├── worker-default.log
    └── deploy.log

Além do diretório inicial, Cipi cria estes arquivos de sistema:

PHP-FPM pool: /etc/php/8.5/fpm/pool.d/meu aplicativo.conf (user=myapp; omitido para Octane aplicativos)
Octane (v5+): Supervisor meu aplicativo-octane + Nginx proxy_pass → 127.0.0.1:81xx
Nginx vhost:  /etc/nginx/sites-available/meu aplicativo
Supervisor:   /etc/supervisor/conf.d/meu aplicativo.conf
Crontab:      * * * * * php artisan schedule:run
MariaDB:      database 'meu aplicativo', user 'meu aplicativo'@'localhost'

O .env é compilado automaticamente com todas as credenciais - nome do banco de dados, senha, token webhook, e APP_KEY. Você nunca precisa tocá-lo manualmente, mas sempre pode editá-lo com cipi app env myapp.