@@ -3,6 +3,8 @@ title: Installation
33description : We have a docker images for amd64 and arm64.
44---
55
6+ import { Accordion , Accordions } from " fumadocs-ui/components/accordion"
7+
68<Callout >
79
810You can find the docker image on [ docker hub] ( https://hub.docker.com/r/shieldauth/shield )
@@ -16,35 +18,250 @@ Before you begin, ensure you have the following installed:
1618- [ Docker] ( https://docs.docker.com/get-docker/ )
1719- [ Docker Compose] ( https://docs.docker.com/compose/install/ )
1820
19- ### 1. Clone the repository
21+ Here are three different ways to deploy Shield Auth, ranging from development to
22+ production setups:
2023
21- #### Using HTTPS
24+ ## 1. Run from Source Code 👨💻
2225
23- ``` bash
26+ Best for development and customization. Build Shield from source code with full
27+ control over the build process.
28+
29+ <Accordions >
30+ <Accordion title = " Detailed building steps" id = " build-from-source"
31+
32+ ### I. Clone the repository
33+
34+ ``` bash title="terminal"
2435git clone https://github.com/shield-auth/shield.git
2536cd shield
2637```
2738
28- ### 2 . Set Up Environment Variables
39+ ### II . Set Up Environment Variables
2940
30- ``` bash
41+ ``` bash title="terminal"
3142cp .env.example .env
3243```
3344
34- ### 3 . Build and Start the Containers
45+ ### III . Build and Start the Containers
3546
36- ``` bash
47+ ``` bash title="terminal"
3748docker compose up -d --build --wait
3849```
3950
40- ### 4. Retrieve Default credentials
51+ ### IV. Retrieve Default credentials
52+
53+ The default credentials are saved in ` /usr/local/bin/logs/default_cred.json ` .
54+ To view them:
55+
56+ ``` bash title="terminal"
57+ docker exec shield cat /usr/local/bin/logs/default_cred.json
58+ ```
59+
60+ _ Note: If the above command doesn't work, use ` docker ps ` to find the correct
61+ container ID for the shield container._
62+
63+ </Accordion >
64+ </Accordions >
65+
66+ ## 2. Run with Containerized Database 🐳
67+
68+ Best for single-server deployments and testing. Complete self-contained setup
69+ with both Shield and PostgreSQL.
70+
71+ <Accordions >
72+ <Accordion title = " Detailed running steps" id = " run-from-docker-image"
73+
74+ ### I. Setup the environment Variables
75+
76+ ``` bash title=".env"
77+ # Shield Service Settings
78+ SHIELD_VERSION=latest
79+ EXTERNAL_PORT=5555 # Shield external port
80+ PORT=5555 # Shield internal port
81+ RUN_MODE=production # development or production
82+
83+ # Database Settings
84+ POSTGRES_VERSION=17
85+ POSTGRES_USER=postgres
86+ POSTGRES_PASSWORD=1234
87+ POSTGRES_PORT=5432
88+ DB_EXTERNAL_PORT=5435 # External database port
89+ DATABASE_NAME=shield
90+
91+ # The DATABASE_URL will be constructed from the above settings
92+ # Format: postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@db:${POSTGRES_PORT}
93+ ```
94+
95+ ### II. Pull the image and start the services
96+
97+ ``` yaml title="docker-compose.yml"
98+ version : " 3.8"
99+
100+ services :
101+ shield :
102+ image : shieldauth/shield:${SHIELD_VERSION:-latest}
103+ container_name : shield
104+ restart : unless-stopped
105+ ports :
106+ - " ${EXTERNAL_PORT:-5555}:${PORT:-5555}" # External:Internal port mapping
107+ depends_on :
108+ db :
109+ condition : service_healthy
110+ environment :
111+ - DATABASE_URL=postgres://${POSTGRES_USER:-postgres}:${POSTGRES_PASSWORD:-1234}@db:${POSTGRES_PORT:-5432}
112+ - DATABASE_NAME=${DATABASE_NAME:-shield}
113+ - RUN_MODE=${RUN_MODE:-production}
114+ - PORT=${PORT:-5555}
115+ healthcheck :
116+ test :
117+ ["CMD-SHELL", "curl -f http://localhost:${PORT:-5555}/health || exit 1"]
118+ interval : 30s
119+ timeout : 10s
120+ retries : 3
121+ start_period : 40s
122+ networks :
123+ - shield-network
124+ logging :
125+ driver : " json-file"
126+ options :
127+ max-size : " 10m"
128+ max-file : " 3"
129+
130+ db :
131+ image : postgres:${POSTGRES_VERSION:-17}
132+ container_name : shield-db
133+ restart : unless-stopped
134+ volumes :
135+ - postgres_data:/var/lib/postgresql/data
136+ environment :
137+ - POSTGRES_USER=${POSTGRES_USER:-postgres}
138+ - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:-1234}
139+ - POSTGRES_DB=${DATABASE_NAME:-shield}
140+ ports :
141+ - " ${DB_EXTERNAL_PORT:-5435}:${POSTGRES_PORT:-5432}"
142+ healthcheck :
143+ test : ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-postgres}"]
144+ interval : 5s
145+ timeout : 5s
146+ retries : 5
147+ networks :
148+ - shield-network
149+ logging :
150+ driver : " json-file"
151+ options :
152+ max-size : " 10m"
153+ max-file : " 3"
154+
155+ networks :
156+ shield-network :
157+ name : shield-${RUN_MODE:-production}
158+
159+ volumes :
160+ postgres_data :
161+ name : shield-postgres-${RUN_MODE:-production}
162+ ` ` `
163+
164+ ` ` ` bash
165+ docker compose up -d
166+ ```
167+
168+ ### III. Retrieve Default credentials
169+
170+ The default credentials are saved in ` /usr/local/bin/logs/default_cred.json ` .
171+ To view them:
172+
173+ ``` bash
174+ docker exec shield cat /usr/local/bin/logs/default_cred.json
175+ ```
176+
177+ _ Note: If the above command doesn't work, use ` docker ps ` to find the correct
178+ container ID for the shield container._
179+
180+ </Accordion >
181+ </Accordions >
182+
183+ ## 3. Run with External Database 📡
184+
185+ Best for production deployments. Use this when connecting to an existing
186+ database or managed database service.
187+
188+ <Accordions >
189+ <Accordion title = " Detailed running steps" id = " run-with-external-database"
190+
191+ ### I. Setup the environment Variables
192+
193+ ``` bash title=".env"
194+ # Required Settings
195+ DATABASE_URL=postgres://user:password@host:5432
196+ DATABASE_NAME=shield
197+
198+ # Optional Settings with defaults
199+ SHIELD_VERSION=latest
200+ EXTERNAL_PORT=8080 # Port exposed to the outside world
201+ PORT=5555 # Port used inside the container
202+ RUN_MODE=production # development or production
203+ ```
204+
205+ ### II. Pull the image and start the services
206+
207+ ``` yaml title="docker-compose.yml"
208+ version : " 3.8"
209+
210+ services :
211+ shield :
212+ image : shieldauth/shield:${SHIELD_VERSION:-latest}
213+ container_name : shield
214+ restart : unless-stopped
215+ ports :
216+ - " ${EXTERNAL_PORT:-5555}:${PORT:-5555}" # External:Internal port mapping
217+ environment :
218+ - DATABASE_URL=${DATABASE_URL:?DATABASE_URL is required}
219+ - DATABASE_NAME=${DATABASE_NAME:?DATABASE_NAME is required}
220+ - RUN_MODE=${RUN_MODE:-production}
221+ - PORT=${PORT:-5555} # Use PORT for application configuration
222+ healthcheck :
223+ test :
224+ ["CMD-SHELL", "curl -f http://localhost:${PORT:-5555}/health || exit 1"]
225+ interval : 30s
226+ timeout : 10s
227+ retries : 3
228+ start_period : 40s
229+ networks :
230+ - shield-network
231+ logging :
232+ driver : " json-file"
233+ options :
234+ max-size : " 10m"
235+ max-file : " 3"
41236
42- The default credentials are saved in `/usr/local/bin/logs/default_cred.json.
237+ networks :
238+ shield-network :
239+ name : shield-${RUN_MODE:-production}
240+ ` ` `
241+
242+ ### III. Retrieve Default credentials
243+
244+ The default credentials are saved in ` /usr/local/bin/logs/default_cred.json`.
43245To view them :
44246
45247` ` ` bash
46- docker exec shield-shield-1 cat /usr/local/bin/logs/default_cred.json
248+ docker exec shield cat /usr/local/bin/logs/default_cred.json
47249` ` `
48250
49251_Note : If the above command doesn't work, use `docker ps` to find the correct
50252container ID for the shield container._
253+
254+ </Accordion>
255+ </Accordions>
256+
257+ 🔄 Deployment Strategy
258+ Choose your deployment option based on your needs :
259+
260+ Development : Use **"Run from Source Code"** for full development capabilities <br />
261+ Testing/Staging : Use **"Run with Containerized Database"** for a complete isolated
262+ environment <br />
263+ Production : Use **"Run with External Database"** for better scalability and management
264+
265+ Each option includes proper logging, health checks, and container management
266+ configurations. Refer to the full documentation for detailed configuration
267+ options and best practices.
0 commit comments