Skip to content

Latest commit

 

History

History
255 lines (167 loc) · 8.12 KB

index.md

File metadata and controls

255 lines (167 loc) · 8.12 KB
Raw

Tug

Welcome on the Tug - a private Composer registry for private PHP packages on AWS Serverless.

This document contains information on how to download, install, and start the API built with:

Prerequisites

This project requires:

If you want to compile and deploy your own version, you must have in addition:

  • the installation of the applications bellow on your local machine (if you prefer to compile your own version):
    • Nodejs
    • NPM or Yarn (to install dependencies)
    • Java (optional, to run database in local)
    • Git (optional)

Services credentials

AWS credentials:

Use the credentials (AWS Access Key ID and the Secret Access Key) from your AWS account, or follow best practices by creating an dedicated IAM user.

Keep the credentials for the step 2.

Note:

If you use the AWS CLI, the credentials and some other parameters are automatically retrieve by the config command.

Github credentials:

Generate a personal access token with the required scopes:

  • repo, included:
    • repo:status
    • repo_deployment
    • public_repo
    • repo:invite

Keep the token for the step 2.

Gitlab credentials:

Generate a personal access token with the required scopes:

  • read_api
  • read_repository

Keep the token for the step 2.

1) Installation

You have the option to install the server in one click or download, compile and deploy your own version of the server:

1.a. Installation with the AWS CloudFormation Launch Stack

This installation process is the easiest and fastest, just click on the "CloudFormation Launch Stack" button, and follow the wizard:

Image of CloudFormation Launch Stack

  1. Then click Next where you can enter a stack name (Tug is a good default)
  2. Click Next
  3. Click Next again on the Options step (leaving the default options selected), to get to the final Review step
  4. a. In the Capabilities section of the Review step: check the acknowledgment checkboxes and click
  5. b. In the Transformations section of the Review step: click on the button "Create a change set"

** Note:**

You can change the AWS region on the first page of wizard, by default, it is the region eu-west-1 that is selected.

1.b. Installation from your local machine

1.b.1. Clone the repository

$ git clone git@github.com:fxpio/tug.git

Or download the archive if you haven't Git.

1.b.2. Setup the project

This command install dependencies, configure the project, create the S3 bucket, package and deploy in AWS Cloud Formation, with API Gateway, Lambda, SQS and IAM.

$ yarn run setup

Notes:

  • You will be prompted to enter your credentials for AWS and Github or Gitlab services, as well as some other settings.
  • If you prefer run the commands separately or run the dev server in local, see this page

Great! Now you can go to the AWS console of CloudFormation to track the deployment status of the stack.

When the deployment process is complete, you can directly use the endpoint of https://<lambda-id>.execute-api.<region>.amazonaws.com/prod/, or create your SSL certificate to use with a custom domain. In this case, see this page.

2) Configure the server

2.1. Create the oAuth token

2.1.a. Create the oAuth token for Github

To connect the server with your Github account, you must configure the Github oAuth token.

To create a oAuth token, open the PWA and in the Settings section click on the Add button of the oAuth token line item. Add your Github personal token just before.

Or run the command:

$ bin/create-github-oauth --token <your-github-personal-token>

Note:

The oAuth token for Github is stored in the DynamoDB with the id config:global and the github-oauth."github.com" attribute.

2.1.b. Create the oAuth token for Gitlab

To connect the server with your Gitlab account, you must configure the Gitlab oAuth token.

To create a oAuth token, open the PWA and in the Settings section click on the Add button of the oAuth token line item. Add your Gitlab personal token just before.

Or run the command:

$ bin/create-gitlab-oauth --token <your-gitlab-personal-token>

Note:

The oAuth token for Gitlab is stored in the DynamoDB with the id config:global and the gitlab-oauth."gitlab.com" attribute.

2.2. Create the token for Webhooks

2.2.a. Create the token for Github Webhooks

To create a token to use in Github webhooks, open the PWA and in the Settings section click on the Add button of the Webhook token line item.

Or run the command:

$ bin/create-github-token

Note:

The token for Github Webhooks is stored in the DynamoDB with the id config:global and the github-webhook."github.com" attribute.

2.2.b. Create the token for Gitlab Webhooks

To create a token to use in Gitlab webhooks, open the PWA and in the Settings section click on the Add button of the Webhook token line item.

Or run the command:

$ bin/create-gitlab-token

Note:

The token for Gitlab Webhooks is stored in the DynamoDB with the id config:global and the gitlab-webhook."gitlab.com" attribute.

2.3. Configure the Webhook in the SCM service

2.3.a. Configure the Github Webhook

In each repository or in a organization, create the webhook with:

  • Payload URL: https://<your-custom-domain-for-tug>
  • Content type: application/json
  • Secret: <your-created-token-for-github-webhooks-in-step-2.2>
  • Which events would you like to trigger this webhook? Just the push event.

2.3.b. Configure the Gitlab Webhook

In each repository or in a organization, create the webhook with:

  • URL: https://<your-custom-domain-for-tug>
  • Secret Token: <your-created-token-for-gitlab-webhooks-in-step-2.2>
  • Trigger: Select the events
    • Push events
    • Tag push events

2.4. Create your first API key

The API keys are to be used with Composer to allow the connection with your Tug.

To create a new API key, open the PWA and click on the Add API key section. Add optionally your fingerprint, and let Tug generate the key.

Or run the command:

$ bin/create-api-key

Note:

The API keys are stored in the DynamoDB with the prefix api-keys:.

3) Enjoy!

Now that you have completed the basic installation and configuration of Tug, you are ready to learn more about using this project.

The following documents are available: