Skip to content

Commit 53c03dd

Browse files
minjnlgcminjnlgc
authored
Merge pull request #80 from UCLComputerScience/deployment-manual
docs: added deployment manual markdown version here as well
2 parents 5903df0 + 3589c72 commit 53c03dd

1 file changed

Lines changed: 292 additions & 30 deletions

File tree

‎README.md‎

Lines changed: 292 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,18 @@
22

33
This is a [Next.js](https://nextjs.org/) project bootstrapped with [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app).
44

5-
## Getting Started
5+
## Table of Contents
6+
7+
1. [Getting Started (Local Development)](#getting-started-local-development)
8+
2. [SendGrid Integration](#sendgrid-integration)
9+
3. [Azure Deployment](#azure-deployment)
10+
- [Azure Virtual Machine Setup](#31-azure-virtual-machine-setup)
11+
- [Azure Blob Storage Setup](#32-azure-blob-storage-setup)
12+
- [VM Connection and Docker Setup](#33-virtual-machine-connection-and-docker-setup)
13+
- [Application Deployment](#34-application-deployment)
14+
- [Verification and Troubleshooting](#35-verification-and-troubleshooting)
15+
16+
## Getting Started (Local Development)
617

718
First, run the development server:
819

@@ -20,32 +31,283 @@ You can start editing the page by modifying `app/page.tsx`. The page auto-update
2031

2132
This project uses [`next/font`](https://nextjs.org/docs/basic-features/font-optimization) to automatically optimize and load Inter, a custom Google Font.
2233

23-
## Send Grid
24-
1. Create a SendGrid Account
25-
Go to https://sendgrid.com/ and sign up for a free account.
26-
27-
2. Authenticate a Sender Email
28-
Before SendGrid will send emails from your app, you must verify a sender identity.
29-
In the SendGrid dashboard, go to Email API > Sender Authentication
30-
Under Single Sender Verification, click "Create a Sender"
31-
Fill out the form:
32-
From Name: (e.g. YourApp Support)
33-
From Email: your personal or test email (e.g. you@example.com)
34-
Reply-To Email: (can be the same as above)
35-
You'll receive a confirmation email — verify it.
36-
Until domain authentication is set up (which we don't require for local dev), each teammate needs to use their own verified sender email.
37-
38-
3. Generate an API Key
39-
Navigate to Settings > API Keys
40-
Click "Create API Key"
41-
Give it a name (e.g., local-dev-key)
42-
Select Full Access or at least "Mail Send"
43-
Click Create & Copy the key
44-
45-
4. Add your key and sender email to a .env file
46-
In your project root, create a .env file (if it doesn't exist already), and add:
47-
SENDGRID_API_KEY=your-api-key-here
48-
SENDGRID_SENDER_EMAIL=your-verified-email@example.com
49-
50-
5. Restart your dev server
51-
If it's already running, make sure to restart so the environment variables are loaded.
34+
## SendGrid Integration
35+
36+
1. **Create a SendGrid Account**
37+
38+
- Go to https://sendgrid.com/ and sign up for a free account.
39+
40+
2. **Authenticate a Sender Email**
41+
42+
- In the SendGrid dashboard, go to Email API > Sender Authentication
43+
- Under Single Sender Verification, click "Create a Sender"
44+
- Fill out the form:
45+
- From Name: (e.g. YourApp Support)
46+
- From Email: your personal or test email (e.g. you@example.com)
47+
- Reply-To Email: (can be the same as above)
48+
- You'll receive a confirmation email — verify it.
49+
- Note: Until domain authentication is set up (which we don't require for local dev), each teammate needs to use their own verified sender email.
50+
51+
3. **Generate an API Key**
52+
53+
- Navigate to Settings > API Keys
54+
- Click "Create API Key"
55+
- Give it a name (e.g., local-dev-key)
56+
- Select Full Access or at least "Mail Send"
57+
- Click Create & Copy the key
58+
59+
4. **Add your key and sender email to a .env file**
60+
61+
- In your project root, create a .env file (if it doesn't exist already), and add:
62+
63+
```
64+
SENDGRID_API_KEY=your-api-key-here
65+
SENDGRID_SENDER_EMAIL=your-verified-email@example.com
66+
```
67+
68+
5. **Restart your dev server**
69+
- If it's already running, make sure to restart so the environment variables are loaded.
70+
71+
## Azure Deployment
72+
73+
This section provides instructions for deploying the application to Azure.
74+
75+
### 3.1 Azure Virtual Machine Setup
76+
77+
1. Navigate to Azure Portal and search for 'Virtual machine'
78+
2. Click 'Create' and select 'Azure virtual machine'
79+
3. Fill in the project details:
80+
- Subscription: Select your subscription
81+
- Resource group: Click 'Create new' to create a new one
82+
4. Configure instance details:
83+
- Virtual machine name: Choose a name for your VM
84+
- Leave all other default settings unchanged
85+
5. Set up administrator account:
86+
- Username: Create a username (make sure to remember this)
87+
- Password: Create a password that meets requirements (e.g., Team3-Spider!)
88+
6. Configure inbound port rules:
89+
- Public inbound ports: Select 'Allow selected ports'
90+
- Select inbound ports: HTTP (80), HTTPS (443), SSH (22)
91+
7. Click 'Review + create', then 'Create' to confirm and deploy
92+
93+
> **⚠️ CHECKPOINT:** Record this important information:
94+
>
95+
> - Public IP address: (example: 20.77.24.37)
96+
> - Administrative username: (example: team3)
97+
> - Administrative password: (example: Team3-Spider!)
98+
99+
### 3.2 Azure Blob Storage Setup
100+
101+
1. Navigate to Azure Portal and search for 'Storage accounts'
102+
2. Click 'Create'
103+
3. Fill in the storage account details:
104+
- Subscription: Same as VM
105+
- Resource group: Same as VM
106+
- Storage account name: Choose a unique name (e.g., 0067team3demostorage)
107+
- Region: Same as VM
108+
- Use default settings for other options
109+
4. Click 'Review + create', then 'Create' to confirm
110+
5. Once created, navigate to the storage account
111+
6. Create a storage container:
112+
- Click 'Containers' in the left menu
113+
- Click '+ Container'
114+
- Name: Enter a name (e.g., 0067team3demostorage-container)
115+
- Click 'Create'
116+
7. Get the connection string:
117+
- Navigate to 'Security + networking' → 'Access keys'
118+
- Click 'Show' next to a connection string and copy it
119+
120+
> **⚠️ CHECKPOINT:** Record this important information:
121+
>
122+
> - Storage account name: (example: 0067team3demostorage)
123+
> - Storage container name: (example: 0067team3demostorage-container)
124+
> - Connection string: (Your full connection string)
125+
126+
### 3.3 Virtual Machine Connection and Docker Setup
127+
128+
#### Connecting to Your VM
129+
130+
1. Open PowerShell (Windows) or Terminal (macOS/Linux)
131+
2. Connect using SSH with your credentials:
132+
```bash
133+
ssh username@ip_address
134+
```
135+
Replace `username` with your administrative username and `ip_address` with your VM's IP address
136+
3. If connecting for the first time, type 'yes' when asked about host authenticity
137+
4. Enter your password when prompted
138+
139+
#### Docker Installation
140+
141+
Execute the following commands one by one:
142+
143+
1. Remove any conflicting packages:
144+
145+
```bash
146+
for pkg in docker.io docker-doc docker-compose docker-compose-v2 podman-docker containerd runc; do sudo apt-get remove $pkg; done
147+
```
148+
149+
2. Update and install prerequisites:
150+
151+
```bash
152+
sudo apt-get update
153+
sudo apt-get install ca-certificates curl gnupg
154+
sudo install -m 0755 -d /etc/apt/keyrings
155+
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.asc
156+
sudo chmod a+r /etc/apt/keyrings/docker.asc
157+
```
158+
159+
3. Add the repository to Apt sources:
160+
161+
```bash
162+
echo \
163+
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
164+
$(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}") stable" | \
165+
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
166+
```
167+
168+
4. Update package index:
169+
170+
```bash
171+
sudo apt-get update
172+
```
173+
174+
5. Install Docker and related packages:
175+
176+
```bash
177+
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin docker-compose
178+
```
179+
180+
6. Verify installation:
181+
```bash
182+
sudo docker run hello-world
183+
```
184+
If successful, you'll see a message indicating that Docker is working correctly.
185+
186+
### 3.4 Application Deployment
187+
188+
#### Getting the Code
189+
190+
1. Clone the GitHub repository:
191+
192+
```bash
193+
git clone https://github.com/UCLComputerScience/COMP0067_2025_Team3.git
194+
```
195+
196+
2. Navigate to the project directory:
197+
```bash
198+
cd COMP0067_2025_Team3
199+
```
200+
201+
#### Setting Up Environment Variables
202+
203+
1. Download the repository code to your local machine
204+
2. Create a file named `.env.production` in the project root with the following content (replace with your values):
205+
206+
```
207+
NEXT_PUBLIC_APP_URL=https://your-domain-name.cloudapp.azure.com
208+
BASEPATH=
209+
NODE_ENV=production
210+
NEXTAUTH_URL=https://your-domain-name.cloudapp.azure.com/
211+
NEXTAUTH_SECRET=L+tNhw7zwbUJF9OIG6n/xGGYWc0CO6kCIzRR+D3AAw0=
212+
213+
AZURE_STORAGE_ACCOUNT_NAME=your-storage-account-name
214+
AZURE_STORAGE_CONTAINER_NAME=your-storage-container-name
215+
AZURE_STORAGE_CONNECTION_STRING=your-connection-string
216+
217+
SENDGRID_API_KEY=your-sendgrid-api-key
218+
SENDGRID_SENDER_EMAIL=your-sender-email
219+
220+
POSTGRES_USER=postgres
221+
POSTGRES_PASSWORD=password
222+
POSTGRES_DB=spider
223+
224+
DATABASE_URL="postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}?schema=public"
225+
```
226+
227+
3. Replace all occurrences of the domain name in the project files:
228+
- Search for "team3docker.uksouth.cloudapp.azure.com"
229+
- Replace with your domain name (e.g., "team3demo.uksouth.cloudapp.azure.com")
230+
231+
#### File Transfer to VM
232+
233+
1. Install and set up an SFTP client (e.g., XFTP, FileZilla):
234+
235+
- Download from [XFTP website](https://www.netsarang.com/en/free-for-home-school/) or your preferred source
236+
- Create a new session with:
237+
- Host: Your VM's IP address
238+
- Username: Your administrative username
239+
- Password: Your administrative password
240+
- Connect to the VM
241+
242+
2. Transfer the following files from your local machine to the VM:
243+
- `docker-compose.yml`
244+
- `docker-compose-init.yml`
245+
- `.env.production`
246+
- The entire `nginx/` folder
247+
248+
#### Deploying the Application
249+
250+
1. Navigate to the project directory on the VM:
251+
252+
```bash
253+
cd COMP0067_2025_Team3
254+
```
255+
256+
2. Create the following volumes:
257+
258+
```bash
259+
sudo docker volume create --name=certbot-etc
260+
sudo docker volume create --name=certbot-www
261+
```
262+
263+
3. Run the Docker Compose Init to get the certificate for the website (once success, press Ctrl + C to exit):
264+
265+
```bash
266+
sudo docker-compose -f docker-compose-init.yml up
267+
```
268+
269+
4. Put the Docker Compose Init down once successfully get the cerficiate:
270+
271+
```bash
272+
sudo docker-compose -f docker-compose-init.yml down
273+
```
274+
275+
5. Run Docker Compose to start the application (might take a long time to build):
276+
```bash
277+
sudo docker-compose up -d --build
278+
```
279+
280+
### 3.5 Verification and Troubleshooting
281+
282+
#### Verification
283+
284+
1. Check if containers are running:
285+
286+
```bash
287+
sudo docker ps
288+
```
289+
290+
2. Access your application through a web browser:
291+
```
292+
https://your-domain-name.cloudapp.azure.com
293+
```
294+
295+
#### Troubleshooting
296+
297+
1. Check container logs:
298+
299+
```bash
300+
sudo docker logs [container_name]
301+
```
302+
303+
2. Restart containers if needed:
304+
305+
```bash
306+
sudo docker-compose -f docker-compose.yml restart
307+
```
308+
309+
3. Remove and recreate containers:
310+
```bash
311+
sudo docker-compose -f docker-compose.yml down
312+
sudo docker-compose -f docker-compose.yml up -d
313+
```

0 commit comments

Comments
 (0)