Core Service

Possibilities

• Modern PHP stack for services: API Platform 3, PHP 8, Symfony 7

• Hexagonal Architecture, DDD & CQRS in PHP

• Built-in docker environment and convenient make cli command

• Official FrankenPHP + embedded Caddy runtime for Symfony, with worker mode enabled in the Docker stack

• A lot of CI checks to ensure the highest code quality that can be (Psalm, PHPInsights, Security checks, Code style fixer)

• Configured testing tools: PHPUnit, Behat

• Much more!

Why you might need it

The Core Service is the backbone of the VilnaCRM ecosystem, providing essential functionalities that power all components of the CRM system. With a robust API, the Core Service ensures seamless integration and scalability across the VilnaCRM platform, enabling efficient operations and consistent user experiences across all services.

License

This software is distributed under the Creative Commons Zero v1.0 Universal license. Please read LICENSE for information on the software availability and distribution.

Minimal installation

Install the latest docker and docker compose

Use make command to set up project and automatically install all needed dependencies

make start

Go to browser and open the link below to access REST API docs

https://localhost/api/docs

You can access the GraphQL endpoint via the link below:

https://localhost/api/graphql

Also, you can see the architecture diagram using the link below

http://localhost:8080/workspace/diagrams

That's it. You should now be ready to use core service!

Workspace Bootstrap

This repository ships with a built-in devcontainer in .devcontainer/devcontainer.json. It is designed to run in a local Coder workspace with Docker access. Bootstrap is handled through scripts/local-coder/*.

When the workspace is created, the post-create script:

• installs CLI tools when the workspace image can provision them
• loads defaults from .devcontainer/workspace-settings.env
• starts the Docker stack with make start, or the equivalent fallback when make is unavailable
• installs PHP dependencies with make install if needed
• runs smoke tests only when GitHub and agent auth are available

After startup, verify the environment:

gh --version
codex --version
bmalph --version
make help

Secure setup for autonomous AI coding agents

Use workspace secrets or environment variables. Do not commit credentials. The default devcontainer bind mounts look for host-side directories under ${HOME}/.openclaw-host-secrets and ${HOME}/.openclaw-host-codex; when they are absent, the workspace bootstrap skips host secret or Codex auth sync gracefully.

• OPENAI_API_KEY: API key for the Codex CLI
• GH_AUTOMATION_TOKEN: GitHub token for non-interactive gh usage
• bootstrap sets git identity for automated commits to:
  • vilnacrm ai bot <info@vilnacrm.com>

The post-create step runs secure bootstrap automatically and then executes startup smoke tests when auth is available. Run the following commands from the repository root in a login shell (bash -l) so PATH and synced credentials are available:

bash scripts/local-coder/setup-secure-agent-env.sh
make bmalph-codex
bash scripts/local-coder/startup-smoke-tests.sh VilnaCRM-Org
bash scripts/local-coder/verify-gh-codex.sh VilnaCRM-Org

What startup-smoke-tests.sh checks:

• gh authentication is available
• repository listing for VilnaCRM-Org works
• bats CLI is available
• bmalph is installed and its Codex dry-run init succeeds
• codex can execute one non-interactive task

Repository-tracked defaults for workspace bootstrap are stored in:

• .devcontainer/workspace-settings.env
• .devcontainer/post-create.sh
• scripts/local-coder/setup-secure-agent-env.sh

What verify-gh-codex.sh checks:

• GitHub auth works
• repository listing for VilnaCRM-Org works
• current PR checks can be queried via gh
• current branch supports git push --dry-run
• bmalph is installed and its Codex dry-run init succeeds
• codex can run basic non-interactive smoke tasks
• tool-calling smoke checks only run when CODEX_TOOL_SMOKE_MODE is not skip

BMALPH for Codex and Claude

The workspace bootstrap installs the bmalph CLI automatically so it is ready for Codex-based development in Coder CE. For local setup, use the make targets:

# Install and verify BMALPH for Codex
make bmalph-codex

# Install and verify BMALPH for Claude Code
make bmalph-claude

# Generic install target
make bmalph-install BMALPH_PLATFORM=codex

To preview how BMALPH would initialize this repository for a platform without changing any tracked files, run:

make bmalph-init BMALPH_PLATFORM=codex BMALPH_DRY_RUN=true
make bmalph-init BMALPH_PLATFORM=claude-code BMALPH_DRY_RUN=true

To install and initialize BMALPH for the current project in one command, run:

make bmalph-setup
make bmalph-setup BMALPH_PLATFORM=claude-code

To generate a specs-only BMALPH planning bundle from a short feature description, invoke the bmad-autonomous-planning skill from your current AI agent session. The canonical workflow lives in .claude/skills/bmad-autonomous-planning/SKILL.md, and Codex can start from .agents/skills/bmad-autonomous-planning/SKILL.md.

Use a short task description and let the main agent orchestrate the BMALPH stages in subagents without repo-local launchers.

bmalph init writes local BMAD/Ralph files such as _bmad/, .ralph/, and platform-specific instruction files. Those generated directories are ignored in git for this repository, so use the dry-run first and initialize locally only when you want the tooling available in your workspace.

Notes:

• secrets are never stored in git; keep them in workspace secrets
• secrets are provided directly to the container runtime
• bootstrap persists required credentials into ~/.config/core-service/agent-secrets.env with chmod 600 for future shell sessions in the same workspace
• no token values are written to repository files
• if you do not provide GH_AUTOMATION_TOKEN, run interactive login: gh auth login -h github.com -w && gh auth setup-git

Using

You can use make command to easily control and work with project locally.

Execute make or make help to see the full list of project commands.

The list of the make possibilities:

aws-load-tests               Execute load tests on AWS
aws-load-tests-cleanup       Clean up AWS resources
bats                         Bats is a TAP-compliant testing framework for Bash
behat                        A php framework for autotesting business expectations
build                        Builds the images (FrankenPHP and support services)
cache-clear                  Clears and warms up the application cache for a given environment and debug mode
cache-warmup                 Warmup the Symfony cache
changelog-generate           Generate changelog from a project's commit messages
check-requirements           Checks requirements for running Symfony and gives useful recommendations to optimize PHP for Symfony.
check-security               Checks security issues in project dependencies. Without arguments, it looks for a "composer.lock" file in the current directory. Pass it explicitly to check a specific "composer.lock" file.
commands                     List all Symfony commands
composer-validate            The validate command validates a given composer.json and composer.lock
coverage-xml                 Create the code coverage report in XML format with PHPUnit
down                         Stop the docker hub
install                      Install vendors according to the current composer.lock file
update                       update vendors according to the current composer.json file
logs                         Show all logs
new-logs                     Show live logs
phpcsfixer                   A tool to automatically fix PHP Coding Standards issues
phpinsights                  Instant PHP quality checks and static analysis tool
phpunit                      The PHP unit testing framework
psalm                        A static analysis tool for finding errors in PHP applications
psalm-security               Psalm security analysis
purge                        Purge cache and logs
sh                           Log to the docker container
start                        Start docker
stop                         Stop docker and the Symfony binary server
up                           Start the docker hub (FrankenPHP, database, redis, support services)

Documentation

Start with the maintained documentation index. It links to setup, architecture, API, database, testing, deployment, operations, troubleshooting, security, and release documentation.

To validate documentation structure and local Markdown links, run:

make docs-check

To validate the docs and generate the PHPDocumentor source API reference into build/docs/phpdoc, run:

make docs

The local API Platform documentation is available at https://localhost/api/docs when the stack is running. For common setup and CI issues, see docs/troubleshooting.md.

Tests

Tests use PHPUnit 9 and Behat.

Test status

If this isn't passing, is there something you can do to help?

Running Load Tests in AWS

This template supports running load tests on AWS using k6, a modern load testing tool, to evaluate the performance of your application under various conditions. You can automate this process using a custom bash script that provisions an EC2 instance, attaches an IAM role, creates an S3 bucket for storing the results, and executes the k6 load tests.

Steps for Running AWS Load Tests

1. Configure AWS CLI:

Before you can interact with AWS, you'll need to configure the AWS CLI with your credentials. Run the following command and provide your AWS Access Key and Secret Access Key. Ensure that your AWS credentials and region are properly set to avoid any permission or region-based issues.

2. Run Load Tests:

The make aws-load-tests runs the script that provisions an EC2 instance, attaches an IAM role, creates an S3 bucket for storing the results, and executes the load tests.

3. Configure CLI Options:

To configure the AWS load testing, pass options through the CLI command to define the AWS environment settings, as needed for your project:

• -r REGION: Specifies the AWS region where the EC2 instance will be launched (e.g., us-east-1)
• -a AMI_ID: Defines the Amazon Machine Image (AMI) ID to use for the EC2 instance (e.g., ami-0e86e20dae9224db8)
• -t INSTANCE_TYPE: Sets the EC2 instance type (e.g., t2.micro)
• -i INSTANCE_TAG: Provides a tag to identify the EC2 instance (e.g., LoadTestInstance)
• -o ROLE_NAME: Specifies the IAM role name for the EC2 instance with write access to S3 (e.g., EC2S3WriteAccessRole)
• -b BRANCH_NAME: Sets the branch name for the project (e.g., main)
• -s SECURITY_GROUP_NAME: Defines the name of the security group to be used for the EC2 instance (e.g., LoadTestSecurityGroup)

4. Executing Load Tests:

Once the EC2 instance is up, the predefined load tests are executed, simulating real-world conditions and workloads on your application.

5. Saving Results to S3:

The results of the load tests are automatically uploaded to an S3 bucket for review and analysis.

6. Scaling and Flexibility:

This approach allows you to scale the infrastructure to suit different performance testing needs, providing insights into how your service performs in a cloud-based, production-like environment.

Cleanup AWS Infrastructure

After the load tests have been completed, it's important to clean up the AWS resources. The make aws-load-tests-cleanup command automates the process of tearing down the EC2 instance, security groups, and other related AWS resources.

Note: This project utilizes AWS free tier services (EC2 micro instances, free security groups, free images, and volumes up to 30 GB), which minimizes cost concerns during AWS operations. However, it's still important to clean up resources to avoid any potential charges beyond the free tier limits.

Repository Synchronization

This template is automatically synchronized with other repositories in our ecosystem. Whenever changes are made to the template, those changes are propagated to dependent projects, ensuring they stay up to date with the latest improvements and best practices.

We use this synchronization feature, for example, in the user-service repository.

The synchronization is powered by the actions-template-sync GitHub Action, which automates the process of propagating updates from this template to other projects.

Handling Workflow Permissions Error

When setting up the repository synchronization, you may encounter permission-related issues. Below are two methods to resolve common workflow permissions errors: using a Personal Access Token (PAT) or using a GitHub App.

Option 1: Using a Personal Access Token (PAT)

Details on how to configure and use a PAT for repository synchronization can be found in the TEMPLATE_SYNC_PAT.md file inside the .github directory.

Option 2: Using a GitHub App

For projects that prefer GitHub App authentication, please refer to the TEMPLATE_SYNC_APP.md file in the .github directory for setup instructions and examples.

Security

Please disclose any vulnerabilities found responsibly – report security issues to the maintainers privately.

See SECURITY and Security advisories on GitHub.

Contributing

Please submit bug reports, suggestions, and pull requests to the GitHub issue tracker.

We're particularly interested in fixing edge cases, expanding test coverage, and updating translations.

If you found a mistake in the docs, or want to add something, go ahead and amend the wiki – anyone can edit it.

Sponsorship

Development time and resources for this repository are provided by VilnaCRM, the free and opensource CRM system.

Donations are very welcome, whether in beer 🍺, T-shirts 👕, or cold, hard cash 💰. Sponsorship through GitHub is a simple and convenient way to say "thank you" to maintainers and contributors – just click the "Sponsor" button on the project page. If your company uses this template, consider taking part in the VilnaCRM's enterprise support program.

Changelog

See changelog.