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.

Durante a instalação, o assistente pede sua chave pública SSH (formatos aceitos: ssh-rsa, ssh-ed25519, ecdsa) antes de qualquer pacote ser instalado. Cipi cria um dedicado cipi Usuário Linux para administrador SSH acesso e aplica proteção SSH: o login root está desabilitado, cipi usa apenas chave pública (grupo cipi-ssh), usuários do aplicativo (grupo cipi-apps) pode se conectar com senha. Entrar as tentativas são limitadas a 3 com um período de carência de 20 segundos e 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. As chaves SSH coladas são automaticamente higienizados – comentários, retornos de carro e excesso de espaços em branco são removidos antes validação.

Instalação padrão

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

Instalação não interativa

Para configurações automatizadas, passe sua chave pública SSH por meio do SSH_PUBKEY variá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 por meio do integrado 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 registros HTTP — 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 (somente 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 KVM ou host bare-metal executando Ubuntu com um 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 — veja aplicativos 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 clientes GUI (TablePlus, DBeaver, Sequel Pro), webhook URL 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 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, corridas artisan 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

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:

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 aplicativos Octane)
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.