Corpen Quickstart: Install, Configure, and Run Locally

Corpen can be running locally in minutes. This guide covers two paths: Docker Compose, which bundles the PHP/Apache runtime into a pre-built image and is the fastest way to get a production-like environment on any OS, and Manual setup, which gives you full control over the stack using your local PHP, Composer, and Node.js toolchain. Both paths result in the same working application.

Prerequisites

Before starting, make sure you have the following available in your environment:

Requirement	Minimum Version	Notes
PHP	8.2	Extensions required: `pdo_mysql`, `gd`, `zip`, `bcmath`
Composer	2.x	Dependency manager for PHP
Node.js	18	Required by Vite for frontend asset compilation
MySQL / MariaDB	8.0 / 10.6	Application database
Redis	any	Optional — used for cache and session drivers if configured

Installation

Docker Compose
Manual Setup

The docker-compose.yml file defines a single app service built from the project’s Dockerfile. It maps container port 80 to host port 83, mounts the entire project directory as a volume, and reads environment variables from your .env file. The Dockerfile is based on php:8.4-apache and installs Composer, Node.js 18 (via NVM), and all required PHP extensions automatically.

You must create and configure your .env file before running docker compose up. The container reads database credentials, storage keys, and the APP_KEY from the .env file at startup. Running migrations against an unconfigured database will fail.

Clone the repository

git clone https://github.com/corpentunida-org/corpen.git
cd corpen

Create and configure the environment file

Corpen does not ship a committed .env.example. Create your own based on standard Laravel variables and the services Corpen uses:

cp .env.example .env   # if a sample exists, otherwise create manually

At minimum, set the following keys in .env:

APP_NAME=Corpen
APP_ENV=local
APP_KEY=                     # Generated in the next step
APP_DEBUG=true
APP_URL=http://localhost:83

DB_CONNECTION=mysql
DB_HOST=your_db_host
DB_PORT=3306
DB_DATABASE=corpen
DB_USERNAME=root
DB_PASSWORD=secret

FILESYSTEM_DISK=local

# Optional: AWS S3 (used by Archivo, Inventario, Cartera modules)
AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
AWS_DEFAULT_REGION=
AWS_BUCKET=

# Optional: Google Cloud Storage
GOOGLE_CLOUD_PROJECT_ID=
GOOGLE_CLOUD_STORAGE_BUCKET=

Build and start the container

The Dockerfile runs composer install, npm install, and npm run build automatically during the image build. The Apache virtual host is pre-configured to serve from /var/www/html/public.

docker compose up --build -d

The application will be available at http://localhost:83 once the container is healthy.

Generate the application key

Run Artisan inside the running container:

docker compose exec app php artisan key:generate

Run database migrations

docker compose exec app php artisan migrate

This executes all migrations in database/migrations/, creating the full schema including Spatie permission tables (2024_11_05_135024_create_permission_tables.php) and all module-specific tables.

Seed roles, users, and geography data

The DatabaseSeeder calls RoleSeeder (creates roles admin, exequial, creditos, seguros, read), UserSeeder, and GeoColombiaSeeder (populates Colombian department and municipality data used throughout the platform):

docker compose exec app php artisan db:seed

Open Corpen in your browser

Navigate to http://localhost:83. You will be redirected to the Jetstream login page. Log in with the credentials created by UserSeeder. After authentication, IndexController reads your assigned role and redirects you to the appropriate module landing page.

The manual path gives you hot-module replacement via npm run dev and the standard php artisan serve development server — ideal for active development.

Configure your .env file before running php artisan migrate. The migration runner must be able to connect to a live MySQL/MariaDB database. Running without a valid DB_* configuration will throw a connection error and leave your database in a partially migrated state.

Clone the repository

git clone https://github.com/corpentunida-org/corpen.git
cd corpen

Install PHP dependencies

composer install

Install Node.js dependencies

npm install

Create and configure the environment file

cp .env.example .env

Edit .env and set your DB_* connection values. For local development with the default local disk, you can leave the AWS and Google Cloud variables empty.

Generate the application key

php artisan key:generate

Create the storage symlink

php artisan storage:link

Run database migrations

php artisan migrate

Seed roles, users, and geography data

php artisan db:seed

This runs RoleSeeder (roles: admin, exequial, creditos, seguros, read), UserSeeder, and GeoColombiaSeeder.

Start the asset compiler and development server

Open two terminal windows. In the first, start Vite:

npm run dev

In the second, start the Laravel development server:

php artisan serve

The application will be available at http://localhost:8000.

Open Corpen in your browser

Navigate to http://localhost:8000. Log in with your seeded credentials. The IndexController reads your actions table role assignment and redirects you to your module’s default landing page (admin.users.index, exequial.asociados.index, seguros.poliza.index, etc.).

After logging in, Corpen does not display a generic dashboard. Instead, IndexController@index queries the roles table joined with the actions table for the authenticated user and performs a role-based redirect:

Role	Lands on
`admin`	`/users` — User management panel
`exequial`	`/exequiales/asociados` — Exequial associates list
`seguros`	`/seguros/poliza` — Insurance policies index
`cinco`	`/cinco/terceros` — Five-percent fund third parties
`soporte`	`/soportes/soportes` — Support tickets list
other	`welcome` view

To access modules beyond the role landing page, a user must be granted direct permissions via Spatie’s model_has_permissions table. The custom CanDirect middleware (registered as the candirect alias) checks getDirectPermissions() — not role-inherited permissions — making per-user module access explicit and auditable. Assign permissions through the /permisos admin panel after seeding.

Building for Production

When deploying beyond the Docker path (e.g., to a VPS or cloud instance), compile assets and warm the caches:

npm run build
php artisan config:cache
php artisan route:cache
php artisan view:cache

The Dockerfile runs npm run build and php artisan view:cache during its build stage. For containerized production deployments, run php artisan config:cache and php artisan route:cache as a post-start step or add them to the container’s entrypoint script, since those commands require a live database connection that is not available at image build time.

Overview

Setup & Configuration

Corpen Quickstart: Install, Configure, and Run Locally

Prerequisites

Installation

Building for Production

Build docs developers (and LLMs) love

Overview

Setup & Configuration

Documentation Index

​Prerequisites

​Installation

​First Login and Role-Based Access

​Building for Production

Build docs developers (and LLMs) love

Prerequisites

Installation

First Login and Role-Based Access

Building for Production