<aside> ⚠️ This documentation is for users with technical knowledge and is intended to guide users to spin up production and staging environments of the Connected Places platform.
</aside>
Metadata
Author: @Mike
Status: Complete
Date created: April 4, 2023
Last reviewed: April 4, 2023
Next review: April 5, 2024
Questions? Send us an email and we'll get back to you.
Start by cloning the latest version of the API repository from Github in your favorite terminal/command line interface:
git clone <https://github.com/Connected-Places/api.git>
Once cloned, copy the .env.example file to create your own .env version. See the environment variables guide for more information on each variable and expected values. The defaults within the example provided will be sufficient to get you started.
cd api
cp .env.example .env
Spin up the docker containers using the convenience script and use the detach flag -d so they run the background.
./develop up -d
<aside> ℹ️ After starting the Docker containers as described above, you should wait a minute or two before progressing to the next steps. This is due to the MySQL and Elasticsearch containers taking a few minutes to fully boot up.
</aside>
You can check the status of the containers by running:
./develop
Once the containers are fully running, install the dependencies
./develop composer install
./develop npm install
Then compile the static assets using:
./develop npm run dev
The application key is a unique and private key per instance that is used for encrypting and decrypting data within the app. Generate a new key for your local machine by running:
./develop artisan key:generate
This command should automatically update the APP_KEY environment variables stored in your .env file. If it doesn’t manually update it with the output from the command above.
Run the Laravel migrations to create the schema within the database (MySQL by default):
./develop artisan migrate
<aside>
ℹ️ If you receive connection errors whilst attempting to run the migrations, ensure that the MySQL Docker container is running (./develop will output the running docker containers) and ensure that the credentials and connection settings in .env are correct.
</aside>
Generate the encryption keys Passport needs in order to generate secure access tokens. The generated keys are not kept in source control:
./develop artisan passport:keys
The above command will create two file within the storage folder. Copy and paste the contents of storage/oauth-private.key into the PASSPORT_PRIVATE_KEY variable in your .env file.
Then, copy and paste the content of storage/oauth-public.key into the PASSPORT_PUBLIC_KEY variable in your .env file.
<aside>
⚠️ You will need to surround the contents of the keys in your .env file within double quotation marks.
</aside>
Run the custom artisan command to create the first Global Admin user account for the platform:
./develop artisan ck:create-user <first-name> <last-name> <email> <phone-number>
# e.g.
# ./develop artisan ck:create-user Joe Bloggs [email protected] 07900000001
<aside> ⚠️ Take a note of the password outputted as you will need to use this to login to the API/Admin app
</aside>
<aside> ℹ️ A valid mobile phone number is required for each user, as a two-factor SMS token will be sent to the specified mobile upon login when the application is in production mode.
</aside>
Create an OAuth client for the admin app (and any other clients) by running the custom artisan command:
./develop artisan ck:create-oauth-client <name> <redirect-uri> [--first-party]
# e.g.
# ./develop artisan ck:create-oauth-client AdminClient <http://0.0.0.0:8080/login> --first-party
<aside> ⚠️ Take a note of the Client ID and Client Secret outputted as you will need to use these when configuring the Admin app / other applications. See Admin Installation.
</aside>
Run the custom artisan command to create/update the Elasticsearch index:
./develop artisan ck:reindex-elasticsearch
The default docker configuration doesn’t expose any ports. As a minimum, we want to expose port 80 so we can interface with our API endpoints over HTTP. You may want to interface with other services such as MySQL, Redis or Elasticsearch directly whilst using the development instance.
Create a docker-compose.override.yml file in the same directory as the docker-compose.yml (usually the root of the repository) and specify what services you want to expose:
services:
app:
ports:
- 80:80
# Uncomment below if you want to expose the MySQL service
# mysql:
# ports:
# - 3306:3306
Restart the docker containers:
./develop down
./develop up -d
The Connected Places API is exposed on port 80. You can verify that the installation succeed by visiting http://0.0.0.0 on your local machine whilst the containers are running.
You should be presented with the Connected Places API homepage where you can login using the details you specified above and the initial password that was outputted from the command 🎉
<aside>
❓ Not able to access the API via HTTP? Be sure to check you have correctly exposed port 80 or check out some of the troubleshooting section.
</aside>
<aside> ℹ️ Most of the functionality within the API also has at least one test case associated with it, but more often than not a handful. There are over 1,100 tests within the API repository and as such, running them all will take a while - at least 15minutes.
</aside>
To run all tests:
./develop composer test
To run only the PHPUnit tests:
./develop composer test:unit
To run only the code style tests:
# Run linter.
./develop composer test:style
# Fix linting errors.
./develop composer fix:style
A convenience script ./develop is provided which acts as a wrapper around the docker compose command. You can run any regular command (e.g. ./develop up) or one of the follow custom commands along with any associated arguments you wish to pass to the command:
./develop <command> <argument 1> <argument 2>
# E.g.
# ./develop composer install
Available commands:
art or artisan