Laravel Localstack Project

Introduction

This project is a starting point for running Laravel with Localstack for local AWS service emulation. It is perfect for any project running on AWS. It provides a Docker-based development environment for easy setup and testing.

The implementation is based on the following blog posts:

These articles offer in-depth explanations of the concepts and techniques used in this project.

Prerequisites

Docker and Docker Compose
Git

Getting Started

Follow these steps to set up and run the project:

Clone the repository:

git clone https://github.com/einar-hansen/laravel-vapor-localstack.git
cd laravel-vapor-localstack

Set up the environment:

# Copy the .env file
cp .env.example .env

# Make the shell scripts executable
chmod +x docker/localstack/init-aws.sh
chmod +x docker/node/entrypoint.sh 
chmod +x install-composer.sh

Install dependencies:

# Install npm dependencies
docker compose run --rm node npm install

# Download Composer
./install-composer.sh

# Install Composer dependencies
docker compose run --rm php-fpm php composer.phar install

Set up the application:

# Generate application key
docker compose run --rm php-fpm php artisan key:generate

# Run migrations
docker compose run --rm php-fpm php artisan migrate

Start the application:
```
docker compose up -d
```
Access the application: Open http://localhost:8000 in your browser.

Development

Shell / CLI

You can enter a running container by using the exec command:

# Shell
docker compose -f docker-compose.yml exec php-fpm sh

# Open Tinker
docker compose -f docker-compose.yml exec php-fpm php artisan tinker

# Open Node shell
docker compose -f docker-compose.yml exec node sh

# Open Localstack shell
docker compose -f docker-compose.yml exec localstack sh

Composer

The Laravel Vapor PHP image doesn't include Composer by default. We use a script to download it on-demand:

# Download Composer (if not already done)
./install-composer.sh

# Run Composer commands
docker compose run --rm php-fpm php composer.phar [command]

# Run Composer inside the PHP container
docker compose -f docker-compose.yml exec php-fpm php composer.phar [command]

Node

The Node environment is configured to run in the background:

# Install dependencies (if not already done)
docker compose run --rm node npm install

# Run npm commands
docker compose run --rm node npm [command]

# Run npm commands inside the node container
docker compose -f docker-compose.yml exec node npm [command]

Laravel Artisan

Execute Artisan commands within the Docker environment:

docker compose -f docker-compose.yml exec php-fpm php artisan tinker

Localstack

This project uses Localstack to emulate AWS services locally, allowing you to develop and test AWS integrations without connecting to actual AWS services.

Configuration

Localstack is configured in the docker-compose.yml file and starts automatically with other services when you run docker compose up.

Interacting with Localstack

Use the AWS CLI with the --endpoint-url parameter to interact with Localstack:

docker compose -f docker-compose.yml exec localstack sh

# Inside the Localstack container you can run awslocal
awslocal [command]
# Example: awslocal sqs create-queue --queue-name my-queue

Init Script

The docker/localstack/init-aws.sh script initializes necessary AWS resources in Localstack when the container starts. You can modify this script to set up additional resources as needed.

Laravel Vapor Local Development

This project includes configurations for running Laravel Vapor locally. Refer to the Running Laravel Vapor Locally blog post for detailed information on how this is implemented.

Troubleshooting

If you encounter issues:

Verify all containers are running:
```
docker compose ps
```
Check container logs:
```
docker compose logs [service-name]
```
Rebuild containers if needed:
```
docker compose build --no-cache
```
Ensure Localstack is properly initialized:
```
docker compose logs localstack
```

Additional Resources

Contributing

We welcome contributions to improve this project. Please follow these steps:

Fork the repository
Create a new branch for your feature or bug fix
Make your changes and commit them with a clear commit message
Push your changes to your fork
Create a pull request with a description of your changes

Please ensure your code adheres to the existing style and include tests for new features.

License

This project is open-sourced software licensed under the MIT license.