The Accessibility Exchange

The Accessibility Exchange is a two-year initiative managed by the Institute for Research and Development on Inclusion and Society (IRIS) that sets out to create an online platform which will support processes where people with disabilities have the power to make sure that policies, programs, and services by federally regulated organizations are accessible to them and respect their human rights. Current consultation processes are built on a foundation of systemic ableism—they lack accountability, follow-through, and don't honour the expertise of people with disabilities.

The Accessibility Exchange platform is co-designed and developed by the Inclusive Design Research Centre at OCAD University.

Technical Details

The platform is built as a progressive web application using the Laravel 12 framework.

Installation

For general deployment information, please see the Laravel 12.x deployment documentation.

The platform requires the following:

• PHP >= 8.4 with required extensions
• MySQL >= 5.7
• Composer >= 2.0
• Node >= 24

Optionally you may wish to install NVM to make node version management easier.

The deployment process should follow all the recommended optimization processes.

Development environments

In development environments, a deployment should be followed by running a fresh migration and the development database seeder:

php artisan migrate:fresh --seeder DevSeeder

NOTE: This will overwrite all existing database tables.

The application can also be run without the dev/test data but still needs to be seeded with the required data:

php artisan migrate:fresh --seed

NOTE: This will overwrite all existing database tables.

Production environments

In production environments, a deployment should be followed by running all available migrations:

php artisan migrate

If this is the first installation and there is no pre-existing data in the database the database must be seeded with:

php artisan db:seed

Development

Local Development Using Herd

Setup Instructions

1. Install Herd.

2. Install Xdebug (macOS/Windows) or PCOV (macOS/Windows) for code coverage.

3. Fork and clone the project repository (easiest with the Github CLI):

   gh repo fork accessibility-exchange/platform --clone
   cd platform

4. Create a .env file from the included example file:

   cp .env.example .env

   Then, change the APP_ENV value to local:

   APP_ENV=local

5. Generate an encryption key for CipherSweet:

   openssl rand -hex 32

   Add it to your .env file:

   CIPHERSWEET_KEY="<your key>"

6. Install Composer and NPM dependencies:

   # install composer dependencies
   composer install
   # To use the version of npm specified in .nvmrc.
   # requires https://github.com/nvm-sh/nvm
   nvm use
   # install node dependencies
   npm ci

7. Generate an application key:

   php artisan key:generate

8. Create the testing env file

   cp .env .env.testing

   Change the APP_ENV value to local:

   APP_ENV=testing

   Change the DB_DATABASE value to tae-testing:

   DB_DATABASE=tae-test

9. Create a database for development and one for running tests:

   mysql -uroot -e "create database accessibilityexchange;"
   mysql -uroot -e "create database tae-test;"

10. Run the required database migrations:

    php artisan migrate
    php artisan migrate --env=testing

11. Download the application fonts:

    php artisan google-fonts:fetch

12. Tell Herd to serve the application:

    herd link

13. Install Mailpit so that you can access transactional email from the platform:

    brew install mailpit
    brew services start mailpit

    Then, make sure that your .env file contains the following values:

    MAIL_MAILER=smtp
    MAIL_HOST=127.0.0.1
    MAIL_PORT=1025

    You will now be able to access mail that the platform sends by visiting http://127.0.0.1:8025 or http://localhost:8025. For more information and additional configuration options, read the Mailpit documentation.

14. If you wish to run your local site with SSL, you will need to change the APP_URL to https://platform.test in .env and then run herd secure.

For comprehensive instructions, consult the Laravel documentation. Here's an overview of how some key tasks can be carried out using Herd:

• Composer commands may be executed by using composer <command>.
• NVM commands may be executed by using nvm <command>.
• NPM commands may be executed by using npm <command>.
• Artisan commands may be executed by using php artisan <command>.

Herd supports debuging via XDebug. The article "Activating XDebug on Visual Studio Code & Laravel Herd" can help if you are having trouble getting it setup with VS Code.

Local development using Docker and Nix

Setup Instructions

1. Install Nix for your system.
2. Run nix-shell.
3. If you are wanting to run Docker, follow the steps for your platform:
   • Linux: On Linux, there are added aliases dstart & dstop that will start and stop the Docker daemon, which runs using rootlesskit.
     • When using rootless, ensure that it is set up and allowed to run on privileged ports. See: Exposing Privileged Ports.
     • You will also want to change the socket path with the following command:

       export DOCKER_HOST=unix:///run/user/1000/docker.sock

   • Other Systems: You will need to have Docker installed and running.

Entering Development Environment

Each time you want to have your terminal environment setup you will want to run nix-shell to make sure you have your aliases and packages setup.

Aliases

✔️ All commands assume they're run from the project root directory where docker-compose.yml exists and the user has entered the nix shell by first running nix-shell.

🧰 1. Docker Compose (dc, dexit, etc.)

Command	Description
dc <command>	Runs any docker-compose command (e.g., dc ps, dc exec...)
dcbp	Builds the platform.test service
dcupd	Starts containers in detached mode
dcdn	Stops and removes containers
dex [options] <service> <cmd>	Executes an non-interactive command in a running container
dexit [options] <service> <cmd>	Executes an interactive command in a running container
dexp	Opens a Bash shell in platform.test as user www-data

---

📷 2. Docker Images (img, imgrm, etc.)

Command	Description
img <command>	Runs any docker image command
imgls	Lists all Docker images
imglsp	Lists only platform-related images (platform*) with their name:tag
imgrmp	Prompts for confirmation before removing platform-related images
imgrm	Removes specified Docker images manually
imgprune	Removes all unused images (no confirmation)

---

📄 3. Docker Logs (log, logf, logt, etc.)

Command	Description
log <container>	Shows logs for a specific container
logf <container>	Follows (tails) logs for a specific container
logt	Tails logs for platform.test with last 100 lines
logp	Tails logs for platform.proxy with last 100 lines
logsql	Tails logs for platform.mysql with last 100 lines
taill	Tails Laravel application logs with last 100 lines
tailt, tailp, tailsql	Show static last 100 lines (not tailing) for respective containers

---

💾 4. Docker Volumes (vol, volrmp, etc.)

Command	Description
vol <command>	Runs any docker volume command
vols	Lists all volumes
volsp	Lists only platform-specific volumes (e.g., platform.mysql, platform.redis)
volrmp	Prompts for confirmation before removing matched platform volumes
volrm	Removes specified volume manually
volprune	Removes all unused volumes (no confirmation)

---

⭐ 5. Laravel Artisan (artisan, tinker, etc.) within container

Command	Description
analyze	Runs composer analyze and vendor/bin/phpstan analyze inside platform.test container
artisan <command>	Runs any Laravel Artisan command inside platform.test container
comp <command>	Runs any Composer command inside platform.test container
pint	Runs vendor/bin/pint command inside platform.test container
tinker	Shortcut for artisan tinker
test	Shortcut for artisan test

Example:

artisan make:model User -mf

is equivalent to:

docker-compose exec -it --user www-data platform.test php artisan make:model User -mf

---

⭐ 6. Composer local commands run on the codebase

Command	Description
format	Runs composer format on the codebase
localize	Runs composer localize on the codebase

---

⚛️ 7. Kubernetes (kflush, kflushall, etc.)

These are custom deployment helpers that trigger Laravel deploy:local and deploy:global commands across Laravel pods in Kubernetes clusters.

Command	Description
kflush development	Flushes all pods in iris-accessibility-development namespace
kflush staging	Flushes all pods in iris-accessibility-staging namespace
kflush production	Flushes all pods in iris-accessibility-production namespace
kflushall	Flushes pods in all three environments (dev → stag → prod)
kflushd, kflushs, kflushp	Shortcuts for flushing dev/stag/prod respectively

Internals of kflush <env>

• Finds all app-* pods in the correct namespace
• Runs php artisan deploy:local on each pod
• Runs php artisan deploy:global only once (on the first pod)

---

🧪 Example Usage Overview

Docker Compose

dc ps                     # Show running services
dcupd                     # Start environment
dexp                      # Open shell in app

Docker Images

imglsp                    # List platform images
imgrmp                    # Remove platform images after confirming

Docker Logs

logt                      # View recent logs for app
logf platform.test        # Tail logs for app

Docker Volumes

volsp                     # List platform volumes
volrmp                    # Remove them safely

Laravel

artisan migrate           # Run migrations
artisan make:controller   # Generate controller
tinker                    # Start Laravel Tinker

Kubernetes

kflushd                   # Run kflush in dev environment
kflushall                 # Run kflush dev, staging, and prod environments

---

📝 Legend

| Symbol | Meaning | | ------ | -------------------------------------------------- | ---------------------------------------- | | $@ | Passes all arguments received by a function | | -r | Prevents execution if no input is given to xargs | | -p | Prompts for confirmation before executing | | | grep ... | Filters output based on pattern matching |

Environment Setup

If the .env file does not exist, the script automatically generates it using .env.local.template and random secrets:

• CIPHERSWEET_KEY (32-byte hex string)
• DB_PASSWORD (16-byte hex string)
• DB_ROOT_PASSWORD (24-byte hex string)
• REDIS_PASSWORD (20-byte hex string)
• APP_KEY (generated using php artisan key:generate)
• WWWUSER (set to current user ID)

Ensure .env.local.template is available before running the script.

Rootless Docker Support

For users running dockerd-rootless, the script provides:

• Aliases:

  alias dstart="dockerd-rootless&"
  alias dstop="pkill dockerd"

• Instructions to set the correct Docker socket:

  export DOCKER_HOST=unix://$XDG_RUNTIME_DIR/docker.sock

• To allow privileged ports, run:

  echo 1 | sudo tee /proc/sys/net/ipv4/ip_unprivileged_port_start

Troubleshooting

Changes are missing in the container

• Rebuild the container and relaunch with the following command dc build platform.test && dc up -d.

Cannot reach site using browser

• Visit the site using the SSL proxy to make sure assets load https://localhost.
• Check that all containers are up and running using the following command docker ps -a and check for container with the name platform.test and check the status column to see if it says Up.
• If it's not up then try to check logs to see if there is an error with the command dc logs -f platform.test. This should help you resolve what might be missing.

Running tests

The project uses Pest for testing. For more information about testing Laravel, read the documentation.

If you make changes to the database, you may need to run the migrations in the test database.

php artisan migrate --env=testing

Development workflow

• This project uses Conventional Commits, enforced by commitlint. All commit messages and pull request titles must follow these standards.
• The dev branch contains features that have been prototyped and gone through one or more co-design sessions.
• Feature development must take place in a fork, in a branch based on the dev branch. Feature branches must be named according to the format feat/<feature>.
• Before opening a pull request, developers should run composer format && composer analyze && php artisan test --coverage to ensure that their code is properly formatted, does not cause static analysis errors, and passes tests. Depending on the code coverage, more tests may need to be written to ensure that code coverage does not drop.
• Once a feature is ready to merge into dev, the merge must be performed using a squash commit.
• The production branch contains refined features that are considered production-ready.
• Prereleases must be tagged from the dev branch.
• Releases must be tagged from the production branch.

Working with markdown

In other Laravel applications you may see methods such as Str::markdown() and Str::inlineMarkdown() used. In general we attempt to avoid using these methods and instead favour using the provided safe_markdown() and safe_inlineMarkdown helpers. These methods will escape HTML used in a markdown string, strip unsafe links, and escape replacements. They are also tied into the localization system, and will populate their strings into the string packages, just as __() would. The safe_markdown() and safe_inlineMarkdown() methods should not be called with {!! !!} as their output will safely pass through {{ }}. This provides an additional layer of protection in cases where you may have mixed types output to the template or make a mistake.

{{ safe_markdown('**hello :location**', ['location' => '**World**']) }}
{{-- <p><strong>Hello **World**</strong></p> --}}

If you need to unescape a replacement you can use a ! at the start of the placeholder name (e.g. :!placeholder).

{{ safe_markdown('**hello :!location**', ['location' => '<em>World</em>']) }}
{{-- <p><strong>Hello <em>World</em></strong></p> --}}

There are some cases where you may still wish to use the Str markdown helpers, such as when handling admin input (e.g. resource collection information). In these special cases, make sure to call the Laravel markdown helpers with the config('markdown') argument to escape HTML and remove unsafe links.

{!! Str::markdown('<em>Hello **World**</em>', config('markdown')) !!}
{{-- <p>&lt;em&gt;Hello <strong>World</strong>&lt;/em&gt;</p> --}}

Mail notification templates

By default Laravel supports a mixture of markdown and HTML in mail notification templates. However, in this application we've modified the templates to only support HTML. This aligns the behaviour of the mail templates with that of the site's blade templates.

Supported application environments

The application environment is set by specifying the APP_ENV environment variable. See Environment Configuration docs for more information.

APP_ENV	Description
local	For local development; i.e. on a developers machine.
dev	For nightly builds build and deployed from the "dev" branch.
staging	For deploys from the "staging" branch. Used to test changes in a production like environment before going live.
production	For deploys from the "production" branch. The live production released code.

Amongst other things, the application environment can be used to prevent tasks from running or requiring confirmation before running, e.g. in production running php artisan migrate:fresh requires confirmation. It can also be used to limit output in blade templates using the @env() or @production directives (See: Environment Directives docs)

Custom Artisan Commands

deploy:global

Purpose

Runs other console commands in order and should be commands that are only run once across multiple deploying container.

deploy:local

Purpose

Runs other console commands in order and should be commands that should be run on each deploying container.

app:migrate-data

Purpose

Runs data migrations that cannot be included in the DB migrations. Should only be run oce across a multiple deploying container.

notifications:remove:old

Purpose

Removes older notifications.

Options

option	Description
--days=	*required - The number of days which notifications older than will be deleted from the notifications database table.

app:refresh-dev

Purpose

NOTE: Does not run in the production environment.

Runs a development database refresh. Places the site in maintenance mode while the database is being refreshed and reseeded.

seo:clear

Purpose

Removes the robots.txt and sitemap files.

seo:generate

Purpose

Generates the robots.txt and sitemap files.

seo:clear-robots

Purpose

Removes the robots.txt file.

seo:generate-robots

Purpose

Generates the robots.txt file.

seo:clear-sitemap

Purpose

Removes the sitemap file.

seo:generate-sitemap

Purpose

Generates the sitemap file.

License

The Accessibility Exchange platform is available under the BSD 3-Clause License.