src/management_guide.qmd

---
title: "User and AWS instance management guide"
format:
  html:
    toc: true # Enable the table of contents
    toc-depth: 3 # Include headings up to level 2 (##)
    toc-title: "On this page" # Optional: Title for your TOC
---

This guide gives an overview of how to manage users of the redaction app, and how to start, stop, and manage instances of the app running on AWS Cloud.

# User management guide

This guide provides an overview for administrators to manage users within an AWS Cognito User Pool, specifically for an application utilising phone-app-based Two-Factor Authentication (2FA).

## Managing Users in AWS Cognito User Pools

AWS Cognito User Pools provide a secure and scalable user directory for your applications. This guide focuses on common administrative tasks within the AWS Management Console.

### Accessing Your User Pool

1.  Log in to the AWS Management Console.
2.  Navigate to **Cognito** (you can use the search bar).
3.  In the left navigation pane, select **User Pools**.
4.  Click on the name of the user pool associated with your redaction app.

### Creating Users

Creating a new user in Cognito involves setting their initial credentials and attributes.

1.  From your User Pool's dashboard, click on the **Users** tab.
2.  Click the **Create user** button.
3.  **Username:** Enter a unique username for the user. This is what they will use to log in.
4.  **Temporary password:**
    * Select **Generate a password** to have Cognito create a strong, temporary password.
    * Alternatively, you can choose **Set a password** and enter one manually. If you do this, ensure it meets the password policy configured for your user pool.
    * **Important:** Cognito will typically require users to change this temporary password upon their first login.
5.  **Email:** Enter the user's email address. This is crucial for communication and potentially for password recovery if configured.
6.  **Phone number (optional):** The phone number is not needed for login or user management in this app, you can leave this blank.
7.  **Mark email as verified/Mark phone number as verified:** For new users, you can choose to automatically verify their email and/or phone number. If unchecked, the user might need to verify these themselves during the signup process (depending on your User Pool's verification settings).
8.  **Groups (optional):** If you have defined groups in your user pool, you can add the user to relevant groups here. Groups are useful for managing permissions and access control within your application.
9.  Click **Create user**.

### Information to Give to Users to Sign Up

Once a user is created, they'll need specific information to access the application.

* **Application URL:** The web address of your redaction app's login page.
* **Username:** The username you created for them in Cognito.
* **Temporary Password:** The temporary password you generated or set.
* **Instructions for First Login:**
    * "Upon your first login, you will be prompted to change your temporary password to a new, secure password."
    * "You will also need to set up Two-Factor Authentication using a phone authenticator app (e.g., Google Authenticator, Authy)."

### Resetting User Access (Password Reset)

If a user forgets their password or needs their access reset, you can do this in the console.

1.  From your User Pool's dashboard, click on the **Users** tab.
2.  Locate the user you wish to reset. You can use the search bar.
3.  Click on the user's username.
4.  On the user details page, click the **Reset password** button.
5.  Cognito will generate a new temporary password and mark the user to change it on next login.
6.  **Important:** You will need to communicate this new temporary password to the user securely.

### Two-Factor Authentication (2FA) with Apps Only

Your application uses phone app-based 2FA. This section covers what administrators need to know.

#### How it Works for the User

When a user logs in for the first time or when 2FA is enabled for their account, they will be prompted to set up 2FA. This typically involves:

1.  **Scanning a QR Code:** The application will display a QR code.
2.  **Using an Authenticator App:** The user opens their authenticator app (e.g., Google Authenticator, Authy, Microsoft Authenticator) and scans the QR code.
3.  **Entering a Code:** The authenticator app will generate a time-based one-time password (TOTP). The user enters this code into the application to verify the setup.

#### Administrator's Role in 2FA

As an administrator, you generally don't directly "set up" the user's 2FA device in the console. The user performs this self-enrollment process within the application. However, you can manage the 2FA status of a user:

1.  **Enabling/Disabling 2FA for a User:**
    * From your User Pool's dashboard, click on the **Users** tab.
    * Click on the user's username.
    * Under the "Multi-factor authentication (MFA)" section, you'll see the current MFA status.
    * If 2FA is not enabled, you might have the option to "Enable MFA" for the user. If your user pool requires 2FA, it might be automatically enabled upon signup.
    * You can also **Disable MFA** for a user if necessary. This will remove their registered 2FA device and they will no longer be prompted for a 2FA code during login until they re-enroll.
2.  **Removing a User's 2FA Device:** If a user loses their phone or needs to re-configure 2FA, you can remove their existing MFA device.
    * On the user's details page, under the "Multi-factor authentication (MFA)" section, you will see a list of registered MFA devices (if any).
    * Select the device and click **Remove**.
    * The next time the user logs in, they will be prompted to set up 2FA again.

### Other Useful Information for Administrators

* **User Status:** In the "Users" tab, you'll see the status of each user (e.g., `CONFIRMED`, `UNCONFIRMED`, `FORCE_CHANGE_PASSWORD`, `ARCHIVED`, `COMPROMISED`).
    * `CONFIRMED`: User has confirmed their account and set their password.
    * `UNCONFIRMED`: User has been created but hasn't confirmed their account (e.g., through email verification) or changed their temporary password.
    * `FORCE_CHANGE_PASSWORD`: User must change their password on next login.
* **Searching and Filtering Users:** The "Users" tab provides search and filtering options to quickly find specific users or groups of users.
* **User Attributes:** You can view and sometimes edit user attributes (like email, phone number, custom attributes) on the user's detail page.
* **Groups:**
    * You can create and manage groups under the **Groups** tab of your User Pool.
    * Groups are useful for organising users and applying different permissions or configurations through AWS Identity and Access Management (IAM) roles.
* **User Pool Settings:**
    * Explore the various settings under the **User Pool Properties** tab (e.g., Policies, MFA and verifications, Message customisations).
    * **Policies:** Define password complexity requirements.
    * **MFA and verifications:** Configure whether MFA is optional, required, or disabled, and the types of MFA allowed (SMS, TOTP). Ensure "Authenticator apps" is enabled for your setup.
    * **Message customisations:** Customise the email and SMS messages sent by Cognito (e.g., for verification codes, password resets).
* **Monitoring and Logging:**
    * Integrate your Cognito User Pool with AWS CloudWatch to monitor user activities and potential issues.
    * Enable CloudTrail logging for Cognito to track API calls and administrative actions.
* **Security Best Practices:**
    * Always use strong, unique passwords for your AWS console login.
    * Enable MFA for your AWS console login.
    * Regularly review user access and permissions.
    * Educate users on strong password practices and the importance of 2FA.

By understanding these features and following best practices, administrators can effectively manage users within their AWS Cognito User Pool, ensuring secure and smooth operation of their redaction application.

# Guide to running app instances on AWS

This guide provides basic instructions for administrators to manage service tasks within AWS Elastic Container Service (ECS) using the AWS Management Console, focusing on scaling services on and off and forcing redeployments.

## Basic Service Task Management in AWS ECS Console

AWS Elastic Container Service (ECS) allows you to run, stop, and manage Docker containers on a cluster. This guide focuses on managing your ECS *services*, which maintain a desired number of tasks (container instances).

### Accessing Your ECS Cluster and Services

1.  Log in to the AWS Management Console.
2.  Navigate to **ECS (Elastic Container Service)** (you can use the search bar).
3.  In the left navigation pane, select **Clusters**.
4.  Click on the name of the ECS cluster where your redaction app's service is running.

### Understanding Services and Tasks

Before we dive into management, let's clarify key concepts:

* **Task Definition:** A blueprint for your application. It specifies the Docker image, CPU, memory, environment variables, port mappings, and other configurations for your containers.
* **Task:** An actual running instance of a task definition. It's an individual container or a set of tightly coupled containers running together.
* **Service:** A mechanism that allows you to run and maintain a specified number of identical tasks simultaneously in an ECS cluster. The service ensures that if a task fails or stops, it's replaced. It also handles load balancing and scaling.

### Setting the Number of Running Tasks to 0 (Turning Everything Off)

Setting the desired number of tasks to 0 for a service effectively "turns off" your application by stopping all its running containers.

1.  From your Cluster's dashboard, click on the **Services** tab.
2.  Locate the service associated with your redaction app (e.g., `redaction-app-service`).
3.  Select the service by checking the box next to its name.
4.  Click the **Update** button.
5.  On the "Configure service" page, find the **Number of tasks** field.
6.  Change the value in this field to `0`.
7.  Scroll to the bottom and click **Update service**.

**What happens next:**

* ECS will begin terminating all running tasks associated with that service.
* The "Running tasks" count for your service will gradually decrease to 0.
* Your application will become inaccessible as its containers are stopped.

**Important Considerations:**

* **Cost Savings:** Setting tasks to 0 can save costs by stopping the consumption of compute resources (CPU, memory) for your containers.
* **Associated Resources:** This action *only* stops the ECS tasks. It does not stop underlying EC2 instances (if using EC2 launch type), associated databases, load balancers, or other AWS resources. You'll need to manage those separately if you want to completely shut down your environment.
* **Container Images:** Your Docker images will still reside in Amazon ECR (or wherever you store them).
* **Downtime:** This action will cause immediate downtime for your application.

### Turning the Desired Number of Tasks On

To bring your application back online, you'll set the desired number of tasks to your operational value (usually 1 or more).

1.  From your Cluster's dashboard, click on the **Services** tab.
2.  Locate the service associated with your redaction app.
3.  Select the service by checking the box next to its name.
4.  Click the **Update** button.
5.  On the "Configure service" page, find the **Number of tasks** field.
6.  Change the value in this field to your desired number of running tasks (e.g., `1`, `2`, etc.).
7.  Scroll to the bottom and click **Update service**.

**What happens next:**

* ECS will begin launching new tasks based on your service's configuration and task definition.
* The "Running tasks" count will increase until it reaches your desired number.
* Once tasks are running and healthy (according to your health checks), your application should become accessible again.

**Important Considerations:**

* **Startup Time:** Allow some time for tasks to pull images, start containers, and pass health checks before your application is fully available.
* **Resource Availability:** Ensure your ECS cluster has sufficient available resources (EC2 instances or Fargate capacity) to launch the desired number of tasks.

### Forcing Redeployment

Forcing a redeployment is useful when you've updated your task definition (e.g., pushed a new Docker image, changed environment variables) but the service hasn't automatically picked up the new version. It's also useful for "restarting" a service.

1.  From your Cluster's dashboard, click on the **Services** tab.
2.  Locate the service you want to redeploy.
3.  Select the service by checking the box next to its name.
4.  Click the **Update** button.
5.  On the "Configure service" page, scroll down to the **Deployment options** section.
6.  Check the box next to **Force new deployment**.
7.  Scroll to the bottom and click **Update service**.

**What happens next:**

* ECS will initiate a new deployment for your service.
* It will launch new tasks using the *latest active task definition revision* associated with your service.
* Existing tasks will be drained and terminated according to your service's deployment configuration (e.g., `minimum healthy percent`, `maximum percent`).
* This process effectively replaces all running tasks with fresh instances.

**Important Considerations:**

* **Latest Task Definition:** Ensure you have activated the correct and latest task definition revision before forcing a new deployment if your intention is to deploy new code. You can update the task definition used by a service via the "Update" service flow.
* **Downtime (minimal if configured correctly):** If your service has a properly configured load balancer and healthy deployment settings (e.g., blue/green or rolling updates), forced redeployments should result in minimal to no downtime. ECS will bring up new tasks before shutting down old ones.
* **Troubleshooting:** If a deployment gets stuck or tasks fail to start, check the "Events" tab of your service for error messages. Also, check the CloudWatch logs for your tasks.

### Other Useful Information for Administrators

* **Service Events:** On your service's detail page, click the **Events** tab. This provides a chronological log of actions taken by the ECS service, such as task launches, stops, and scaling events. This is invaluable for troubleshooting.
* **Tasks Tab:** On your service's detail page, click the **Tasks** tab to see a list of all individual tasks running (or recently stopped) for that service. You can click on individual tasks to view their details, including logs, network configuration, and CPU/memory utilisation.
* **Logs:** For each task, you can often find a link to its CloudWatch Logs under the "Logs" section of the task details. This is critical for debugging application errors.
* **Metrics:** The **Metrics** tab on your service provides graphs for CPU utilisation, memory utilisation, and the number of running tasks, helping you monitor your service's performance.
* **Deployment Configuration:** When updating a service, review the **Deployment options** section. This allows you to control how new deployments are rolled out (e.g., minimum healthy percent, maximum percent). Proper configuration here ensures minimal impact during updates.
* **Auto Scaling (beyond basic management):** For dynamic scaling based on demand, explore **Service Auto Scaling**. This allows ECS to automatically adjust the desired number of tasks up or down based on metrics like CPU utilisation or request count.
* **Task Definitions:** Before updating a service, you might need to create a new revision of your task definition if you're deploying new code or configuration changes to your containers. You can find Task Definitions in the left navigation pane under ECS.

By mastering these basic service management operations in the AWS Console, administrators can effectively control the lifecycle of their ECS-based applications.