Guía de instalación

Hay dos caminos. Ambos instalan la misma aplicación; cambia cómo se ejecuta.

Con Docker

• Docker Engine con el plugin Docker Compose (el comando es docker compose, con espacio).
• Git, para clonar y actualizar el repositorio.
• No necesitas PHP, Composer ni Node.js en el servidor: viven en las imágenes, y los assets compilados (public/build) vienen en el repositorio.

Instalación manual

Servidor

Para uso personal o familiar basta un VPS pequeño: 1–2 vCPU, 2 GB de RAM y 10 GB de disco son una referencia orientativa. Si vas a abrir el registro a más personas, planea más memoria.

El stack levanta cinco servicios: app (PHP-FPM), nginx (expone el puerto 9000), postgres, queue (worker de colas) y scheduler (tareas programadas).

1. Clona el repositorio

git clone https://github.com/xenthrall/cafe-del-tiempo.git
cd cafe-del-tiempo

2. Crea el archivo de entorno

Usa la plantilla pensada para Docker, no .env.example:

cp .env.docker.example .env

Edita .env y ajusta al menos APP_URL, DB_PASSWORD y APP_INSTANCE. Tienes el detalle de cada variable en Configuración del entorno.

3. Genera la clave de la aplicación

Genera la clave desde el host y pégala en APP_KEY. Así evitas problemas de permisos al escribir el .env desde el contenedor.

echo "base64:$(openssl rand -base64 32)"

4. Construye y levanta los servicios

docker compose build
docker compose up -d
docker compose ps

Al arrancar, el contenedor app espera a PostgreSQL y optimiza Laravel. Revisa que no haya errores con docker compose logs -f app.

5. Ejecuta las migraciones

Las migraciones no corren solas al arrancar, a propósito. Ejecútalas la primera vez y en cada actualización:

docker compose exec app php artisan migrate --force

6. Crea tu usuario administrador y entra

docker compose exec app php artisan user:create --admin

Abre http://TU_IP:9000/app e inicia sesión. Más opciones del comando en Tu primer usuario.

En tu máquina (desarrollo o prueba)

Con SQLite no necesitas configurar ninguna base de datos:

git clone https://github.com/xenthrall/cafe-del-tiempo.git
cd cafe-del-tiempo
composer install && npm install
cp .env.example .env && php artisan key:generate
php artisan migrate
npm run build
php artisan serve

Abre http://localhost:8000/app. Para desarrollar con recarga automática, usa composer run dev en lugar de php artisan serve.

En un servidor sin Docker

1. Apunta tu servidor web (Nginx, Apache o Caddy) a la carpeta public/ del proyecto.
2. Instala dependencias sin paquetes de desarrollo:
   bash Copiar

   composer install --no-dev --optimize-autoloader
   npm ci && npm run build

3. Configura el .env con APP_ENV=production, APP_DEBUG=false y tu base de datos (ver configuración).
4. Migra y optimiza:
   bash Copiar

   php artisan migrate --force
   php artisan optimize

5. Da permisos de escritura al usuario del servidor web sobre storage/ y bootstrap/cache/.
6. Configura el worker de colas y las tareas programadas, como se explica en Colas y tareas programadas.

Estas son las variables del .env que conviene revisar. El resto de valores de las plantillas ya funcionan tal cual.

Crea usuarios desde la terminal con user:create (en Docker, antepone docker compose exec app). El comando pide nombre, correo y contraseña:

php artisan user:create --admin

• Con --admin, el usuario entra al panel personal (/app) y al de administración de la instancia (/system).
• Sin --admin, solo entra a /app.
• Puedes pasar --name y --email para no escribirlos en el prompt. La contraseña siempre se pide de forma interactiva, para que no quede en el historial de la terminal.

Desde /system también puedes crear las cuentas del resto de personas sin abrir el registro público.

La aplicación necesita dos procesos en segundo plano: un worker de colas y el programador de tareas, que ejecuta los respaldos diarios. Con Docker ya corren en los servicios queue y scheduler.

En una instalación manual, mantén el worker activo con Supervisor o systemd:

php artisan queue:work --tries=3 --timeout=90

Y agrega el programador al cron del usuario del servidor web:

* * * * * cd /ruta/a/cafe-del-tiempo && php artisan schedule:run >> /dev/null 2>&1

Pon un proxy inverso con HTTPS delante del puerto de la aplicación: Caddy, Nginx, Traefik o un túnel como Cloudflare Tunnel. La aplicación ya confía en las cabeceras X-Forwarded-* del proxy, así que solo tienes que:

1. Poner APP_URL=https://tu-dominio.
2. Poner SESSION_SECURE_COOKIE=true.
3. Reiniciar: docker compose up -d.

La aplicación respalda la base de datos todos los días a las 02:00 y limpia los respaldos antiguos a la 01:30. Los archivos se suben al disco r2_private, así que necesitas configurar las variables R2_PRIVATE_*.

• Solo se respalda la base de datos: el código ya está en Git, y respaldar archivos incluiría el .env con tus credenciales.
• Guarda una copia del .env fuera del servidor: el respaldo no la incluye.
• Para probar la configuración, lanza un respaldo manual: php artisan backup:run --only-db.

Con Docker:

git pull origin main
docker compose up -d --build
docker compose exec app php artisan migrate --force

En una instalación manual:

git pull origin main
composer install --no-dev --optimize-autoloader
npm ci && npm run build
php artisan migrate --force
php artisan optimize
php artisan queue:restart

¿Algo más? Abre un issue en GitHub.