Cómo instalar Appwrite self-hosted en Ubuntu 24.04

Appwrite es una plataforma backend-as-a-service de código abierto que ofrece autenticación, bases de datos, almacenamiento, funciones y mensajería a través de una API REST y SDKs para web, móvil y servidor. En este tutorial instalarás Appwrite en Ubuntu 24.04 con su instalador oficial basado en Docker, obtendrás un certificado de Let's Encrypt, crearás un proyecto con una clave de API y comprobarás que funciona creando un usuario desde la API.

Requisitos previos

Para seguir esta guía necesitas:

Un servidor con Ubuntu 24.04 LTS, por ejemplo un VPS de CubePath, con al menos 2 vCPU, 4 GB de RAM y 20 GB de disco.
Un usuario no root con privilegios sudo.
Docker Engine y el plugin de Docker Compose instalados desde el repositorio oficial de Docker.
Los puertos 80 y 443 libres: Appwrite trae su propio proxy (Traefik), así que no instales Nginx ni Apache en el mismo servidor.
Un subdominio con un registro A apuntando al servidor. En esta guía se usa appwrite.tudominio.com.

Comprueba que el subdominio resuelve a tu servidor:

dig +short appwrite.tudominio.com

203.0.113.10

Paso 1: Configurar el firewall

Permite SSH y el tráfico web en UFW:

sudo ufw allow OpenSSH
sudo ufw allow 80,443/tcp
sudo ufw enable

Comprueba que nada más escucha en los puertos 80 y 443. La orden no debe devolver ninguna línea:

sudo ss -tlnp | grep -E ':(80|443) '

Paso 2: Ejecutar el instalador de Appwrite

Appwrite se instala con un contenedor que genera el docker-compose.yml y el .env en un directorio appwrite/ y arranca los servicios. Obtén el número de la última versión estable:

APPWRITE_VERSION=$(curl -fsSL https://api.github.com/repos/appwrite/appwrite/releases/latest | grep -oP '"tag_name":\s*"\K[^"]+')
echo "$APPWRITE_VERSION"

1.7.4

Tu versión puede ser más reciente. Desde tu directorio personal, lanza el instalador:

cd ~
sudo docker run -it --rm \
    --volume /var/run/docker.sock:/var/run/docker.sock \
    --volume "$(pwd)"/appwrite:/usr/src/code/appwrite:rw \
    --entrypoint="install" \
    "appwrite/appwrite:${APPWRITE_VERSION}"

El instalador hace varias preguntas. Responde así:

Puertos HTTP y HTTPS: acepta 80 y 443.
Clave secreta (secret API key): acepta la generada o escribe una larga y aleatoria. Cifra datos internos de Appwrite: guárdala en un lugar seguro, porque si la pierdes no podrás recuperar esos datos.
Hostname: appwrite.tudominio.com.
Registro DNS para dominios personalizados (CNAME): el mismo appwrite.tudominio.com.

Al terminar, el instalador descarga las imágenes y arranca los contenedores. Tarda varios minutos.

Paso 3: Verificar la instalación

Entra en el directorio que ha creado el instalador y comprueba el estado de los contenedores:

cd ~/appwrite
sudo docker compose ps --format 'table {{.Name}}\t{{.Status}}'

NAME                           STATUS
appwrite                       Up 3 minutes
appwrite-mariadb               Up 3 minutes
appwrite-redis                 Up 3 minutes
appwrite-traefik               Up 3 minutes
appwrite-worker-certificates   Up 3 minutes
...

Consulta el endpoint de versión, que no necesita autenticación. Si responde por HTTPS sin errores de certificado, Appwrite ya ha obtenido el certificado de Let's Encrypt para tu hostname:

curl -s https://appwrite.tudominio.com/v1/health/version

{"version":"1.7.4"}

La primera petición HTTPS puede tardar unos segundos mientras se emite el certificado. Si ves un error de certificado, espera un minuto y repite.

Paso 4: Crear la cuenta de administración y un proyecto

Abre https://appwrite.tudominio.com en el navegador y regístrate. La primera cuenta es la propietaria de la consola. Por defecto, Appwrite solo permite registrar esa primera cuenta en la consola; compruébalo en el .env:

grep _APP_CONSOLE_WHITELIST_ROOT ~/appwrite/.env

_APP_CONSOLE_WHITELIST_ROOT=enabled

En la consola:

Pulsa Create project, ponle un nombre (por ejemplo Mi aplicación) y anota el Project ID que aparece en la configuración del proyecto.
En Overview > Integrations > API keys, crea una clave llamada servidor con los permisos users.read y users.write. Copia el secreto: es la clave que usará tu backend.
Si vas a usar Appwrite desde una web, añade en Overview > Integrations > Platforms una plataforma Web con el hostname de tu aplicación (por ejemplo app.tudominio.com). Appwrite solo acepta peticiones del navegador desde los hostnames registrados.

Los nombres exactos de los menús pueden variar ligeramente entre versiones de la consola.

Paso 5: Probar la API desde el servidor

Las API de servidor se autentican con las cabeceras X-Appwrite-Project y X-Appwrite-Key. Crea un usuario de prueba, sustituyendo TU_PROJECT_ID, TU_API_KEY y la contraseña (mínimo 8 caracteres):

curl -s -X POST https://appwrite.tudominio.com/v1/users \
  -H "Content-Type: application/json" \
  -H "X-Appwrite-Project: TU_PROJECT_ID" \
  -H "X-Appwrite-Key: TU_API_KEY" \
  -d '{"userId":"unique()","email":"[email protected]","password":"una_contraseña_segura","name":"Usuario de prueba"}'

El valor unique() pide a Appwrite que genere el identificador. La respuesta incluye el usuario creado:

{"$id":"66f3c1a2001e4b7d9a3c","$createdAt":"2026-09-25T10:20:14.512+00:00", ... ,"name":"Usuario de prueba", ... ,"email":"[email protected]", ...}

Lista los usuarios del proyecto para confirmarlo:

curl -s https://appwrite.tudominio.com/v1/users \
  -H "X-Appwrite-Project: TU_PROJECT_ID" \
  -H "X-Appwrite-Key: TU_API_KEY"

El campo total de la respuesta debe valer 1. El usuario aparece también en la sección Auth de la consola.

Desde el navegador, tu aplicación usa el SDK web (npm install appwrite) sin clave de API; los permisos dependen de la sesión del usuario:

import { Client, Account } from "appwrite";

const client = new Client()
  .setEndpoint("https://appwrite.tudominio.com/v1")
  .setProject("TU_PROJECT_ID");

const account = new Account(client);

await account.createEmailPasswordSession("[email protected]", "una_contraseña_segura");
const user = await account.get();
console.log(user.email);

Importante

la clave de API da acceso de servidor a tu proyecto. No la incluyas nunca en código que se ejecute en el navegador o en una app móvil.

Paso 6: Configurar el envío de correo

Appwrite necesita un servidor SMTP para enviar verificaciones de correo, recuperación de contraseña e invitaciones a equipos. Edita el .env:

nano ~/appwrite/.env

Ajusta estas variables con los datos de tu proveedor de correo:

_APP_SYSTEM_EMAIL_NAME=Mi aplicación
[email protected]
_APP_SMTP_HOST=smtp.tudominio.com
_APP_SMTP_PORT=587
_APP_SMTP_SECURE=tls
[email protected]
_APP_SMTP_PASSWORD=tu_contraseña_smtp

Recrea los contenedores para que lean el .env actualizado. docker compose restart no es suficiente:

cd ~/appwrite
sudo docker compose up -d

Prueba el envío con Forgot password en la pantalla de inicio de sesión de la consola. Si no llega el correo, revisa los logs del worker de correo con sudo docker compose logs appwrite-worker-mails --tail 50.

Paso 7: Actualizar Appwrite

Antes de actualizar, lee las notas de versión y haz una copia de seguridad de los volúmenes de Docker. La actualización usa el mismo contenedor con el punto de entrada upgrade, lanzado desde el directorio que contiene appwrite/:

cd ~
sudo docker run -it --rm \
    --volume /var/run/docker.sock:/var/run/docker.sock \
    --volume "$(pwd)"/appwrite:/usr/src/code/appwrite:rw \
    --entrypoint="upgrade" \
    appwrite/appwrite:NUEVA_VERSION

Después, ejecuta la migración de datos:

cd ~/appwrite
sudo docker compose exec appwrite migrate

Actualiza siempre de versión en versión menor (por ejemplo de 1.6 a 1.7) y ejecuta la migración tras cada salto.

Solución de problemas

El instalador o Traefik fallan con address already in use. Otro servicio ocupa el puerto 80 o 443. Identifícalo con sudo ss -tlnp | grep -E ':(80|443) ' y desinstálalo o detenlo antes de volver a lanzar sudo docker compose up -d en ~/appwrite.

El navegador muestra un certificado autofirmado. Appwrite no pudo obtener el certificado de Let's Encrypt. Comprueba que _APP_DOMAIN en ~/appwrite/.env coincide con tu hostname, que el registro DNS apunta al servidor y que el puerto 80 es accesible desde Internet. Después revisa los logs:

cd ~/appwrite
sudo docker compose logs appwrite-worker-certificates --tail 50

El SDK web devuelve errores de CORS o Invalid Origin. El hostname desde el que se carga tu aplicación no está registrado como plataforma Web en el proyecto. Añádelo en Platforms tal como aparece en la barra del navegador.

Conclusión

Tienes Appwrite funcionando en Ubuntu 24.04 con HTTPS, una cuenta de consola protegida, un proyecto con clave de API y el envío de correo configurado. Como siguientes pasos, puedes crear bases de datos y buckets de almacenamiento desde la consola, activar proveedores OAuth en Auth > Settings y, si vas a usar Functions, configurar un dominio wildcard en _APP_DOMAIN_FUNCTIONS para las funciones.

On this page