Ponlo a correr

Esta guía te lleva de un clon del repositorio a la aplicación corriendo en tu máquina y a ti con sesión iniciada como administrador. La necesitas una vez por máquina.

Qué necesitas instalado

Redis y Memcached son opcionales. Los drivers por omisión de cola, caché y sesión son todos database, así que nada más tiene que estar corriendo.

Los siete pasos

Córrelos desde la raíz del clon, en este orden.

1. Copia el archivo de entorno.

cp .env.example .env

2. Instala las dependencias de PHP.

composer install

Además de instalar paquetes, esto apunta core.hooksPath a scripts/git-hooks, así que desde ahora corre un hook pre-push. Detiene un push cuando a una guía de ayuda le falta su traducción; git push --no-verify lo salta una vez.

3. Genera la llave de la aplicación.

php artisan key:generate

4. Apunta .env a tu base de datos. El bloque depende del motor; ve la siguiente sección. Crea la base de datos antes: la migración no la crea.

5. Corre las migraciones y los seeders.

php artisan migrate --seed

6. Instala las dependencias del frontend y compila los assets.

npm ci && npm run build

7. Enlaza la carpeta pública de archivos.

php artisan storage:link

El bloque de base de datos de .env

.env.example viene con MySQL. Reemplaza el bloque por el de tu motor.

MySQL o MariaDB:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=tu_proyecto
DB_USERNAME=root
DB_PASSWORD=

Para MariaDB pon DB_CONNECTION=mariadb; las demás variables son las mismas.

PostgreSQL:

DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=tu_proyecto
DB_USERNAME=postgres
DB_PASSWORD=

SQLite no necesita servidor. Crea el archivo y nómbralo:

touch database/database.sqlite

DB_CONNECTION=sqlite
DB_DATABASE=/ruta/absoluta/a/tu-proyecto/database/database.sqlite

Si quitas DB_DATABASE por completo, la conexión sqlite cae a database/database.sqlite dentro del proyecto. Dejar el valor laravel de MySQL haría que SQLite buscara un archivo llamado laravel, así que quítalo o reemplázalo.

Todos los motores aceptan también DB_URL como una sola cadena de conexión en lugar de host, puerto, base de datos, usuario y contraseña por separado. El resto de las variables de base de datos está en El archivo de entorno.

Dos variables que arreglar antes de que cargue la primera página

.env.example está escrito para un servidor que tiene Amazon S3 y un mailer transaccional. En una laptop, dos de sus valores van a romper la primera petición o el primer correo.

Pon también APP_URL en la dirección que de verdad vas a abrir. El valor de ejemplo es http://weblabor-base.test, que sólo resuelve si Herd o Valet sirven la carpeta con ese nombre.

Qué crea el seed

php artisan migrate --seed corre DatabaseSeeder, que llama cinco seeders en este orden:

1. PermissionSeeder lee cada recurso del panel y crea un permiso create, retrieve, update y delete por cada uno, más lo que agregues a permissions en config/app.php. Los permisos que ya no existen se borran cuando allow_permisisons_deletion es true, que es su valor por omisión.
2. RoleSeeder crea el rol nombrado en admin_role (admin) y le da todos los permisos, crea un rol llamado client sin ninguno, y crea el default_role si nombras uno.
3. AdminSeeder crea un administrador por cada correo en sudo y le asigna el rol de admin.
4. UserSeeder crea un usuario normal por cada correo en default_users, sin rol.
5. AddOnSeeder crea los complementos listados en el archivo. La lista viene vacía y el seeder termina antes de empezar cuando el paquete de cobros no está instalado.

Los dos seeders de usuarios usan firstOrCreate, así que volver a correr el seed nunca reinicia una contraseña.

Tu primer inicio de sesión

Las cuentas salen de dos arreglos en config/app.php:

'sudo' => [
    '[email protected]',
],

'default_users' => [
    '[email protected]',
],

Pon tu propio correo en sudo antes de sembrar. Si ya sembraste, agrégalo y corre php artisan db:seed --class=AdminSeeder; el seeder sólo crea lo que falta.

Por cada correo, los dos seeders hacen exactamente esto:

• El nombre es la parte antes de la @ convertida en palabras: CarlosEscobar se vuelve Carlos Escobar, admin se vuelve Admin.
• El correo se pasa a minúsculas antes de guardarlo, así que inicias sesión con la forma en minúsculas aunque config/app.php tenga mayúsculas.
• La contraseña es la parte antes de la @, en minúsculas y al revés. [email protected] recibe nimda; [email protected] recibe tset; [email protected] recibe rabocsesolrac.
• El correo se marca como verificado, así que la cuenta se salta la verificación.

AdminSeeder hace una cosa más: si la contraseña guardada sigue siendo la generada, registra una solicitud de cambio de contraseña. La primera vez que ese administrador inicia sesión, el middleware security lo manda a /password/request a elegir una contraseña de verdad antes de llegar a cualquier otra cosa. Los default_users no reciben esa solicitud.

Que una cuenta sea superadministrador no se guarda: el atributo sudo del usuario compara el correo contra la lista sudo en minúsculas cada vez. Quitar un correo del arreglo le quita el privilegio en la siguiente petición, aunque la cuenta conserva el rol de admin hasta que se lo quites en el panel.

Abre el sitio y ve a /login. El inicio de sesión acepta el correo por omisión; la variable LOGIN_IDENTITIES lo amplía a teléfono y usuario. Después de iniciar sesión caes en /app, el valor de home_route en config/app.php, y el panel de administración está en /admin. Tu propio perfil, dispositivos y notificaciones están en /account; ve Tu área de cuenta.

Arranca los servidores

composer dev

Esto corre cuatro procesos en una sola terminal: php artisan serve en el puerto 8000, php artisan queue:listen --tries=1, php artisan pail siguiendo el log, y npm run dev para Vite con recarga en caliente. Pon APP_URL=http://localhost:8000 para que los enlaces que construye la aplicación coincidan con la dirección que abres.

Si sirves la carpeta con Herd, Valet o tu propio servidor web, sólo necesitas Vite:

npm run dev

O sáltate Vite por completo y usa los assets que compilaste en el paso 6.

Todo lo opcional empieza apagado

Planes, complementos, avisos, referidos y seguimiento tienen cada uno una bandera en config/features.php, y toda bandera vale false por omisión. Una función deshabilitada pierde sus rutas y sus entradas de menú, panel de administración incluido. Si al panel le falta una sección que esperabas, es por eso. El PIN, la verificación telefónica, la PWA, el web push, Stripe y el traductor con IA también esperan cada uno sus propias variables. Configura tu proyecto lista las banderas y a dónde lleva cada una.

Cuando no arranca

Los comandos del día a día, las pruebas y las revisiones que corren antes de un push están en Trabaja en el código.