Deploying in a cloud container service
How to deploy the official api docker image in Amazon ECS
To get a greater understanding of ECS (Elastic Container Service) you can take a look at the excellent documentation provided by AWS covering containers, tasks, services and clusters.
From the main dashboard for ECS you can click get started and go through the steps to deploy your instance of the apydox api.
In this section we will provide you a step-by-step approach to deploying the api in ECS. There are a lot of customisations around networking and VPCs we don't cover you may want to implement to provide greater security for your apydox instance.
Creating a cluster
A little introduction to clusters
A cluster is a grouping of services or tasks running in containers that can be logically grouped together by a business requirement such as access. (e.g. a cluster of services that can only be accessed over a private VPN)
You may be a little confused as to why we need a cluster. Amazon ECS does create a cluster for you be default when you first use it but if you need extra security or have a range of services that are core to your business you will want to clearly separate services for internal usage from the business' core services.
Getting off to a flying start
From the dashboard head into the clusters section and click Create Cluster.
You will be presented with the following screen:
From here you will need to select the cluster template appropriate for your use case. In most cases the AWS Fargate Networking only option is the best in terms of costs and still gives you the option of greater security with VPCs and subnets. Another point worth noting is that apydox is something you will deploy for your team(s) to use. Unless your company consists of thousands of software engineers it will be very unlikely that you will need the auto scaling groups the other cluster templates provide.
Once you have selected your cluster template you will be taken to a new screen where you can simply provide the name of your cluster and can create a VPC for the cluster if you wish. You can also add tags to help further group or identify the cluster if you have a lot of clusters deployed to ECS already.
Once you have entered all of these details click Create and the cluster will be created for you.
If you wish to deploy the portal as a docker container as well, you will want to deploy the portal service to the same cluster as the api.
Creating the task definition
Overview of task definitions
A key ingredient to setting up your services in ECS is a task definition. Within ECS the actual instances are managed as services within clusters. These services make use of a task definition like a template for every container that is spun up for a service.
The task definition provides information like the docker image to be used, environment variables to be provided to the container and port mapping from within the container to the host.
Creating your new task definition
From the ECS dashboard click task definitions in the sidebar menu and then click the Create new task definition call to action to begin creating your task definition.
The first thing you will be provided with is a way in which you can select the kind of backing infrastructure for running the containers.
You will need to choose the launch type that is compatible with the cluster template you selected in the Creating a cluster section of this guide.
Once you have chosen your launch type and proceeded by clicking on the next step button you will be presented by a screen that may seem a little daunting. (Depending on how experienced you are with ECS and container orchestration services)
The first field you'll see is the task definition name, simply enter something like apydox-api here.
The next field is an optional task role, it is best to create a custom task role in the IAM dashboard that has permission to interact with elastic container service. Follow the link provided next to the field, set up the role and then select the newly created role as the task role for your new task definition.
Ensure your role has permissions to read from the SSM parameter store if you choose to use the recommended approach of providing environment variables mapped to secure strings stored in the parameter store.
The next section you should see is the task size, specifying the amount of resources used by containers in terms of CPU and memory usage.
If you are using the Fargate launch type you will need to specify a value for both, otherwise you can leave them empty. Depending on the expected usage of the portal and the size of your team(s) you will need to set the resources accordingly. You can always adjust and increase instances of tasks in a service as you need later on.
Container definition
The next section is for providing one or more container definitions. In this case you will only need the one definition for the api.
The image above shows the basic values you need to provide for the main fields in the container definition. Simply entering the public docker image repo in the image field is sufficient as ECS will behave like docker cli by first looking up the public registry from the docker hub.
You will need to be explicit about the version of the apydox api you wish to use as there is no latest version. You can find the tags available here for the different versions of the api.
Next, open the advanced container configuration section and scroll down until you see the following section:
There are three ways to provide the configuration for the API, the best way is to use the AWS Systems Manager Parameter Store, store your secrets as secure strings (encrypted) and reference the values to be populated at runtime for the container just as shown above.
The second way is to simply provide the secret values directly as values in the environment variables section of the task definition using the value option instead of valueFrom. This is less secure as the secrets will be stored as plain text as a part of the task definition.
The third way would be to mount a volume containing a the configuration file containing the secrets. The third method would add a bit more complexity and will also store your secrets as plain text in the storage used for the volume.
Now save your new container definition, review the task definition as a whole and click create to finish saving the task definition.
Creating your apydox service
A quick insight to services
Services in ECS are a similar concept to a docker service defined in a docker-compose file. They provide an execution context for a task definition, or in other words they bring task definitions to life. A service contains one or more instances of the docker containers defined in the associated task definitions and is an independently scalable unit. A service has a schedule manager which will always ensure your desired number of containers/tasks will be running if an instance is to go down.
Getting your service up and running
Navigate to the cluster you set up at the beginning, ensure you open up the services tab and then click the create button. You should be shown a screen similar the following:
Ensure you select the correct launch type that your task definition and cluster supports and then move to the next step once you have provided all the relevant values.
You should then be presented with a view that looks something like this:
This section requires you to configure the VPC and subnets your service will live in. If you have created a specific VPC beforehand ensure you select that, otherwise select the default VPC associated with your AWS account.
To gain public access to the api (From the web ui) you will need to introduce load balancing for your instance of the api, you will need to create a load balancer prior to creating your service. Check out the following link to find out how to set up and configure your load balancer.
You will also need to make use of the AWS Certificate Manager or upload a certificate to accept https traffic for the api. To run apydox you will need to accept https traffic for both the portal web ui and the api.
The section that follows is for service discovery, making your service discoverable via DNS. You can use the default settings or disable service discovery completely by deselecting the Enable service discovery integration checkbox.
Click next step to advance and you will see a screen giving you the option to enable autoscaling, you will likely want to leave autoscaling turned off as per the default selection.
Once you have defined your autoscaling preferences, click next step and you will be taken to an overview of your new service to be reviewed. If you followed all the steps correctly you should be good to go, so go ahead and create your new service!
Updating your apydox api instance
You will want to keep up to date with the latest version of the api to get the latest fixes and features. Updating your version of the apydox api deployed in ECS is a simple process.
Creating a new task definition revision
From the ECS dashboard navigate into the task definitions section. From here you can find the task definition you created for the apydox api. Open up the task definition by clicking on the name, then select the latest revision and click the create new revision button as shown below.
You should now be in the task definition editing mode. Scroll down to the container definition section and open up the apydox api container definition by clicking the container name.
You should now see a view like the following:
Update the image field with the latest version of the docker image, you can find the latest version here as a tag. Once you have updated the image version, click update and then the create button on the task definition editing page to create the new revision of the task definition.
Keep a note of the number of the task definition revision you have just created.
Updating your service to use the latest task definition
Navigate to the clusters dashboard and open up the cluster you created for apydox. Now identify the service you created for the apydox api and click on the service name to open it and then click the update button which will allow you to edit the service.
Simply change the revision of the task definition to the latest revision as shown above and click next step. If you are happy with the networking and load balancing settings then click next step again. You will then be shown the autoscaling settings page, if the current settings are correct click next step for a final time.
Now you will see an overview page of the service, review everything one last time from this page and click update service to use the latest version of the apydox api.
The process will then begin to replace the running service containing the old revision of the task definition with the latest revision.
Last updated
