Project Setup

In This Document

• In This Document
• Project Setup Overview
• Clone the Project
• Set Up the Environment File
• Build and Start Docker Containers
• Install PHP Dependencies
• Install Node.js Dependencies
• Run Migrations
• Generate Application Key
• Link Storage
• Compile Frontend Assets
• Access the Application
• Common Issues and Troubleshooting
• Development Workflow
• Next Steps

This guide provides step-by-step instructions for setting up the project locally using Docker. Make sure you have completed the Docker Installation before proceeding.

Project Setup Overview

Clone the Project

First, clone the project repository and navigate to its directory:

Clone the repository

git clone https://github.com/BemoBit/planet-project.git
cd /your-path/project

warning

Replace /your-path/project with the actual path where you want to clone the project.

Set Up the Environment File

Standard Setup

Copy the example .env file to create your configuration file:

Create environment file

cp .env.example .env

tip

You may need to modify some values in the .env file to match your local environment.

Custom Configuration

If you need a custom configuration:

1. Copy the example file: cp .env.example .env
2. Open the .env file in your favorite editor
3. Update the following values:

.env file

APP_NAME=PlanetProject
APP_ENV=local
APP_DEBUG=true

DB_CONNECTION=mysql
DB_HOST=mysql
DB_PORT=3306
DB_DATABASE=planet
DB_USERNAME=planet_user
DB_PASSWORD=your_secure_password

REDIS_HOST=redis
REDIS_PORT=6379

Build and Start Docker Containers

Standard Setup

Use the following commands to build and start the Docker containers:

Build and start containers

docker compose build
docker compose up -d

Verify that all services are running properly:

Check container status

docker compose ps  # check all services are OK

Expected Output

You should see all services listed with a "running" state.

NAME                COMMAND                  SERVICE             STATUS              PORTS
lsp_app             "docker-php-entrypoi…"   app                 running             0.0.0.0:8080->80/tcp
lsp_mysql           "docker-entrypoint.s…"   mysql               running             0.0.0.0:3306->3306/tcp
lsp_redis           "docker-entrypoint.s…"   redis               running             0.0.0.0:6379->6379/tcp

Rebuild Containers

If you need to rebuild the containers after making changes:

Rebuild containers

docker compose down
docker compose build
docker compose up -d

Install PHP Dependencies

Run the following command inside the lsp_app container to install PHP dependencies:

Install PHP dependencies

docker exec -it -u root lsp_app composer install

note

When prompted for a GitHub token, provide your token. Tokens are required to install specific dependencies.

Install Node.js Dependencies

Install the Node.js dependencies required for the frontend:

Install Node.js dependencies

docker exec -it -u root lsp_app npm install

Run Migrations

Set up the database structure by running migrations:

Run database migrations

docker exec -it -u root lsp_app php artisan migrate

Migration Options

If you need to refresh the database (drop all tables and re-run migrations):

docker exec -it -u root lsp_app php artisan migrate:fresh

To seed the database with sample data:

docker exec -it -u root lsp_app php artisan db:seed

To refresh and seed in one command:

docker exec -it -u root lsp_app php artisan migrate:fresh --seed

Generate Application Key

Generate the application encryption key:

Generate application key

docker exec -it -u root lsp_app php artisan key:generate

Link Storage

Link the storage directory for file uploads:

Link storage directory

docker exec -it -u root lsp_app php artisan storage:link

Compile Frontend Assets

Development

Compile assets for development:

Compile assets for development

docker exec -it -u root lsp_app npm run dev

Production

Compile assets for production:

Compile assets for production

docker exec -it -u root lsp_app npm run prod

Watch Mode

Compile and watch for changes:

Compile and watch for changes

docker exec -it -u root lsp_app npm run watch

Access the Application

Once all the setup steps are complete, you can access the application:

• Web Interface: http://localhost:8080
• API Endpoint: http://localhost:8080/api/v3
• Admin Panel: http://localhost:8080/admin

Default Credentials

For the admin panel, use the following default credentials:

• Username: admin@example.com
• Password: password

Make sure to change these credentials in a production environment!

Common Issues and Troubleshooting

Container not starting

If a container fails to start, check the logs:

docker compose logs [service_name]

Common issues include:

• Port conflicts (another service is using the same port)
• Incorrect environment variables
• Missing dependencies

Permission issues

If you encounter permission issues:

# Fix storage permissions
docker exec -it -u root lsp_app chmod -R 777 storage
docker exec -it -u root lsp_app chmod -R 777 bootstrap/cache

Database connection issues

If you can't connect to the database:

1. Check that the MySQL container is running: docker compose ps mysql
2. Verify your .env database settings match the Docker Compose configuration
3. Try restarting the MySQL container: docker compose restart mysql

Development Workflow

Once your environment is set up, here's a typical development workflow:

1. Make changes to the code
2. Run tests: docker exec -it -u root lsp_app php artisan test
3. Compile assets if needed: docker exec -it -u root lsp_app npm run dev
4. Commit and push your changes

Next Steps

Now that you have set up the project, you can:

1. Explore the API documentation
2. Learn about the development guidelines
3. Start contributing to the project!