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.
The platform is built as a progressive web application using the Laravel 10 framework.
For general deployment information, please see the Laravel 10.x deployment documentation.
The platform requires the following:
Optionally you may wish to install NVM to make node version management easier.
The deployment process should follow all the recommended optimization processes.
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.
In production environments, a deployment should be followed by running all available migrations:
php artisan migrate
Local development uses Laravel Herd.
Install Herd.
Fork and clone the project repository (easiest with the Github CLI):
gh repo fork accessibility-exchange/platform --clone
cd platform
Create a .env
file from the included example file:
cp .env.example .env
Then, change the APP_ENV
value to local
:
APP_ENV=local
Generate an encryption key for CipherSweet:
openssl rand -hex 32
Add it to your .env
file:
CIPHERSWEET_KEY="<your key>"
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
Generate an application key:
php artisan key:generate
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
Create a database for development and one for running tests:
mysql -uroot -e "create database accessibilityexchange;"
mysql -uroot -e "create database tae-test;"
Run the required database migrations:
php artisan migrate
php artisan migrate --env=testing
Download the application fonts:
php artisan google-fonts:fetch
Tell Herd to serve the application:
herd link
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.
For comprehensive instructions, consult the Laravel documentation. Here's an overview of how some key tasks can be carried out using Herd:
composer <command>
.nvm <command>
.npm <command>
.php artisan <command>
.Install docker according to your platform instructions found here.
Clone the repository:
git clone https://github.com/accessibility-exchange/platform.git && cd platform
Create a .env
file from the included example file:
cp .env.local.example .env
Then, change the APP_ENV
value to local
:
APP_ENV=local
Generate an encryption key for CipherSweet:
docker run --rm -it alpine apk add openssl && openssl rand -hex 32
Add it to your .env
file:
CIPHERSWEET_KEY="<your key>"
Generate your database password:
docker run --rm -it alpine apk add openssl && openssl rand -hex 32
Add it to your .env
file:
DB_PASSWORD="<your key>"
Generate your redis password:
docker run --rm -it alpine apk add openssl && openssl rand -hex 20
Add it to your .env
file:
REDIS_PASSWORD="<your key>"
Generate an application key:
docker compose -f docker-compose.local.yml run --rm --entrypoint '' platform.test php artisan key:generate --show
Add it to your .env
file:
APP_KEY="<your key>"
Alter the numerical IDs that PHP will run as in the application container: Reason: your local directories will be mapped into the application container to allow your changes to be viewed in real time.
Find your local user ID & GROUP (Linux & MacOS):
ls -ln
You will see output like below. In the below case user is 1000
and group id is 1001
.
total 1124
drwxr-xr-x 18 1000 1001 4096 Mar 20 12:56 app
-rwxr-xr-x 1 1000 1001 1686 Nov 2 12:10 artisan
Add them to your .env
file:
WWWUSER=<your user id>
WWWGROUP=<your group id>
Re-build you application container after the .env
file updates:
docker compose -f docker-compose.local.yml build platform.test
Start up the entire stack:
docker compose -f docker-compose.local.yml up -d
If you are going to be committing code changes you will want to copy the php packages from the container and install node packages.
docker cp platform.test:/app/vendor ./vendor
nvm use
npm ci
For comprehensive instructions, consult the Laravel documentation. Here's an overview of how some key tasks can be carried out using your containers:
docker exec --user www-data platform.test php artisan <command>
.docker exec --user www-data platform.test npm <command>
.docker exec --user www-data platform.test composer <command>
.docker exec --user www-data -it platform.test bash
.docker exec -it platform.test bash
.Changes are missing in the container
docker compose -f docker-compose.local.yml build platform.test && docker compose -f docker-compose.local.yml up -d
.Cannot reach site using browser
docker ps -a
and check for container with the name platform.test
and check the status column to see if it says Up.docker compose -f docker-compose.local.yml logs -f platform.test
. This should help you resolve what might be missing.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
dev
branch contains features
that have been prototyped and gone through one or more co-design sessions.dev
branch. Feature branches
must be named according to the format feat/<feature>
.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.dev
, the merge must be performed using a squash commit.production
branch contains refined
features that are considered production-ready.dev
branch.production
branch.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><em>Hello <strong>World</strong></em></p> --}}
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.
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)
Runs other console commands in order and should be commands that are only run once across multiple deploying container.
Runs other console commands in order and should be commands that should be run on each deploying container.
Removes older notifications.
option | Description |
---|---|
--days= |
*required - The number of days which notifications older than will be deleted from the notifications database table. |
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.
Removes the robots.txt and sitemap files.
Generates the robots.txt and sitemap files.
Removes the robots.txt file.
Generates the robots.txt file.
Removes the sitemap file.
Generates the sitemap file.
The Accessibility Exchange platform is available under the BSD 3-Clause License.