@cryptotaxi247 / CoPilot
Code Commits Issues Pulls Sessions CI/CD
main
main
mdx 243 lines 4.7 KB
Raw
1 ---
2 title: Install / Upgrade
3 description: Install SOCFortress CoPilot with Docker Compose, retrieve the initial admin password, and safely upgrade.
4 ---
5
6 CoPilot is shipped as Docker images and is intended to be deployed via **Docker Compose**.
7
8 > ❗ WARNING: CoPilot is **not** intended to be exposed directly to the public Internet. Deploy behind a VPN / private network or a properly secured reverse proxy.
9
10 ---
11
12 ## Prereqs
13
14 - A Linux host (VM or bare metal recommended)
15 - [Docker Engine](https://docs.docker.com/get-docker/)
16 - [Docker Compose](https://docs.docker.com/compose/install/)
17
18 ---
19
20 ## Install (Docker Compose)
21
22 ### 1) Get `docker-compose.yml`
23
24 You have two common options:
25
26 **Option A (recommended for most users): clone the repo**
27
28 ```bash
29 git clone https://github.com/socfortress/CoPilot.git
30 cd CoPilot
31 ```
32
33 **Option B: download just the Compose file for a specific release**
34
35 Replace `<VERSION>` with a release tag (example: `v0.1.5`).
36
37 ```bash
38 wget https://raw.githubusercontent.com/socfortress/CoPilot/<VERSION>/docker-compose.yml
39 ```
40
41 ### 2) Create required data paths
42
43 ```bash
44 mkdir -p data
45 mkdir -p data/copilot-mcp
46 ```
47
48 ### 3) Create your `.env`
49
50 Copy from the example and edit as needed:
51
52 ```bash
53 cp .env.example .env
54 nano .env
55 ```
56
57 At minimum, make sure `SERVER_HOST` is correct for your environment.
58
59 ### 4) Start CoPilot
60
61 ```bash
62 docker compose up -d
63 ```
64
65 ### 5) Retrieve the initial admin password
66
67 The **admin password is only printed the first time** CoPilot starts.
68
69 ```bash
70 docker logs "$(docker ps --filter ancestor=ghcr.io/socfortress/copilot-backend:latest --format "{{.ID}}")" 2>&1 | grep "Admin user password"
71 ```
72
73 ### 6) Access the UI
74
75 CoPilot is available on:
76
77 - `https://<your_instance_ip_or_hostname>` (HTTPS / 443)
78
79 By default, an `admin` account is created.
80
81 ---
82
83 ## Helpful Docker daemon settings (DNS / logging / MTU)
84
85 If you run into image pulls / name resolution issues, consider configuring Docker DNS and log rotation.
86
87 Edit:
88
89 ```bash
90 nano /etc/docker/daemon.json
91 ```
92
93 Example:
94
95 ```json
96 {
97 "dns": ["YOUR_DNS_SERVER"],
98 "log-driver": "json-file",
99 "log-opts": {
100 "max-size": "10m",
101 "max-file": "3"
102 }
103 }
104 ```
105
106 If you need to set MTU:
107
108 ```json
109 {
110 "dns": ["YOUR_DNS_SERVER"],
111 "log-driver": "json-file",
112 "log-opts": {
113 "max-size": "10m",
114 "max-file": "3"
115 },
116 "mtu": 1450
117 }
118 ```
119
120 Apply:
121
122 ```bash
123 systemctl daemon-reload
124 systemctl restart docker
125 ```
126
127 ---
128
129 ## TLS / SSL
130
131 By default, CoPilot uses a **self-signed certificate** valid for 365 days from install.
132
133 To use your own certificate:
134
135 1) Generate/obtain a cert/key.
136
137 ```bash
138 # Example self-signed cert
139 openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365
140 ```
141
142 2) Mount the certs into `copilot-frontend` and set `TLS_CERT_PATH` / `TLS_KEY_PATH`.
143
144 ```yaml
145 copilot-frontend:
146 image: ghcr.io/socfortress/copilot-frontend:latest
147 volumes:
148 - PATH_TO_YOUR_CERTS:/etc/letsencrypt
149 environment:
150 - SERVER_HOST=${SERVER_HOST:-localhost}
151 - TLS_CERT_PATH=/etc/letsencrypt/live/${SERVER_HOST}/fullchain.pem
152 - TLS_KEY_PATH=/etc/letsencrypt/live/${SERVER_HOST}/privkey.pem
153 ports:
154 - "80:80"
155 - "443:443"
156 ```
157
158 ---
159
160 ## Customer Portal (Optional)
161
162 CoPilot includes an optional **customer-facing portal** for end users to view cases, alerts, and agents.
163
164 ### Enable the Customer Portal
165
166 In `docker-compose.yml`, the service is commented out by default.
167
168 1) Edit the file:
169
170 ```bash
171 nano docker-compose.yml
172 ```
173
174 2) Uncomment:
175
176 ```yaml
177 copilot-customer-portal:
178 image: ghcr.io/socfortress/copilot-customer-portal:latest
179 environment:
180 - SERVER_HOST=${SERVER_HOST:-localhost}
181 ports:
182 - "8443:443"
183 restart: always
184 ```
185
186 3) Apply:
187
188 ```bash
189 docker compose up -d
190 ```
191
192 4) Access it:
193
194 - `https://<your_instance_ip>:8443`
195
196 ### Customer Portal TLS
197
198 Like the main frontend, it uses a self-signed cert by default. To use your own:
199
200 ```yaml
201 copilot-customer-portal:
202 image: ghcr.io/socfortress/copilot-customer-portal:latest
203 volumes:
204 - PATH_TO_YOUR_CERTS:/etc/letsencrypt
205 environment:
206 - SERVER_HOST=${SERVER_HOST:-localhost}
207 ports:
208 - "8443:443"
209 ```
210
211 ### Creating Customer Portal Users
212
213 Customer portal users are managed via the main CoPilot admin interface:
214
215 1. Log in as an admin
216 2. Navigate to **Users**
217 3. Create a user with the `customer_user` role
218 4. Assign the user to the correct customer organization
219
220 ---
221
222 ## Upgrade
223
224 You’ll likely want to upgrade often as changes ship frequently.
225
226 From your CoPilot directory:
227
228 ```bash
229 docker compose pull
230 docker compose up -d
231 ```
232
233 If you need a clean restart (rare):
234
235 ```bash
236 # This stops containers but keeps named volumes / bind-mounted data intact.
237 docker compose down
238
239 docker compose pull
240 docker compose up -d
241 ```
242
243 > Tip: make sure your persistent `data/` directory is backed up before major upgrades.