Skip to content

Commit b6eeba3

Browse files
gabrielacebalgabrielacebal
authored
Merge pull request #2 from gabrielacebal/feature/development
Edit readme, create agents, setup markdown and docker-ci and smoke-te…
2 parents 4be4ebf + 2b03a09 commit b6eeba3

5 files changed

Lines changed: 872 additions & 252 deletions

File tree

‎.github/workflows/docker-ci.yml‎

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
name: Docker CI
2+
3+
on:
4+
pull_request:
5+
branches:
6+
- main
7+
8+
push:
9+
branches:
10+
- main
11+
12+
env:
13+
REGISTRY: ghcr.io
14+
IMAGE_NAME: ${{ github.repository }}
15+
16+
jobs:
17+
18+
test:
19+
name: Build and Smoke Test
20+
runs-on: ubuntu-latest
21+
22+
permissions:
23+
contents: read
24+
25+
steps:
26+
27+
- name: Checkout repository
28+
uses: actions/checkout@v7
29+
30+
- name: Validate Docker Compose
31+
run: docker compose config
32+
33+
- name: Build containers
34+
run: docker compose build
35+
36+
- name: Start containers
37+
run: docker compose up -d
38+
39+
- name: Wait for API
40+
run: |
41+
for i in {1..30}; do
42+
if curl --fail http://localhost:3000/ > /dev/null 2>&1; then
43+
echo "API is ready"
44+
exit 0
45+
fi
46+
47+
echo "Waiting for API..."
48+
sleep 2
49+
done
50+
51+
echo "API did not become ready"
52+
docker compose logs
53+
exit 1
54+
55+
- name: GET tasks
56+
run: |
57+
curl --fail http://localhost:3000/tasks
58+
59+
- name: POST task
60+
run: |
61+
response=$(curl --fail \
62+
-X POST \
63+
-H "Content-Type: application/json" \
64+
-d '{"title":"GitHub Actions Smoke Test"}' \
65+
http://localhost:3000/tasks)
66+
67+
echo "$response"
68+
69+
task_id=$(echo "$response" | jq -r '.id')
70+
71+
if [ -z "$task_id" ] || [ "$task_id" = "null" ]; then
72+
echo "Task was not created correctly"
73+
exit 1
74+
fi
75+
76+
echo "TASK_ID=$task_id" >> "$GITHUB_ENV"
77+
78+
- name: PUT task
79+
run: |
80+
curl --fail \
81+
-X PUT \
82+
-H "Content-Type: application/json" \
83+
-d '{"completed":true}' \
84+
http://localhost:3000/tasks/$TASK_ID
85+
86+
- name: GET created task
87+
run: |
88+
curl --fail \
89+
http://localhost:3000/tasks/$TASK_ID
90+
91+
- name: DELETE task
92+
run: |
93+
curl --fail \
94+
-X DELETE \
95+
http://localhost:3000/tasks/$TASK_ID
96+
97+
- name: Show container status
98+
if: always()
99+
run: docker compose ps
100+
101+
- name: Show logs on failure
102+
if: failure()
103+
run: docker compose logs
104+
105+
- name: Stop containers
106+
if: always()
107+
run: docker compose down -v
108+
109+
110+
publish:
111+
name: Publish Docker Image
112+
runs-on: ubuntu-latest
113+
114+
needs:
115+
- test
116+
117+
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
118+
119+
permissions:
120+
contents: read
121+
packages: write
122+
123+
steps:
124+
125+
- name: Checkout repository
126+
uses: actions/checkout@v7
127+
128+
- name: Set up Docker Buildx
129+
uses: docker/setup-buildx-action@v4
130+
131+
- name: Login to GitHub Container Registry
132+
uses: docker/login-action@v4
133+
with:
134+
registry: ${{ env.REGISTRY }}
135+
username: ${{ github.actor }}
136+
password: ${{ secrets.GITHUB_TOKEN }}
137+
138+
- name: Docker metadata
139+
id: meta
140+
uses: docker/metadata-action@v6
141+
with:
142+
images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
143+
tags: |
144+
type=raw,value=latest
145+
type=sha
146+
147+
- name: Build and publish image
148+
uses: docker/build-push-action@v7
149+
with:
150+
context: .
151+
push: true
152+
tags: ${{ steps.meta.outputs.tags }}
153+
labels: ${{ steps.meta.outputs.labels }}

‎AGENTS.md‎

Lines changed: 214 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,214 @@
1+
# Agent Instructions
2+
3+
This file defines the rules for AI coding agents working on this repository.
4+
5+
## Project Purpose
6+
7+
`docker-task-api` is responsible for the application and its Docker container lifecycle.
8+
9+
It contains:
10+
11+
* Node.js / Express API
12+
* PostgreSQL integration
13+
* Dockerfile
14+
* Docker Compose local environment
15+
* database initialization
16+
* API helper scripts
17+
* Docker validation
18+
* container image publishing
19+
20+
## Architecture Boundary
21+
22+
Do not introduce Kubernetes resources into this repository.
23+
24+
The following belong in:
25+
26+
https://github.com/gabrielacebal/kubernetes-task-manager
27+
28+
* Deployments
29+
* Services
30+
* Ingress
31+
* ConfigMaps
32+
* Kubernetes Secrets
33+
* namespaces
34+
* HorizontalPodAutoscaler
35+
* Kubernetes probes
36+
* Kubernetes setup scripts
37+
* cluster creation
38+
39+
The expected relationship is:
40+
41+
```text
42+
docker-task-api
43+
|
44+
| build
45+
v
46+
Docker image
47+
|
48+
v
49+
kubernetes-task-manager
50+
```
51+
52+
## Development Rules
53+
54+
When modifying the API:
55+
56+
1. Keep routes under `src/routes`.
57+
2. Keep database access parameterized.
58+
3. Never concatenate request data into SQL queries.
59+
4. Preserve environment-based database configuration.
60+
5. Avoid hardcoded production credentials.
61+
6. Preserve compatibility with Docker Compose.
62+
7. Keep the API stateless except for PostgreSQL persistence.
63+
64+
## Docker Rules
65+
66+
Changes to the application must continue to support:
67+
68+
```bash
69+
docker compose build
70+
docker compose up
71+
```
72+
73+
Do not require Node.js or PostgreSQL to be installed on the host.
74+
75+
The Compose service names are part of the local architecture:
76+
77+
```text
78+
api
79+
database
80+
```
81+
82+
The API must reach PostgreSQL using:
83+
84+
```text
85+
database:5432
86+
```
87+
88+
Do not replace it with `localhost`.
89+
90+
## Validation
91+
92+
Before considering a change complete:
93+
94+
```bash
95+
docker compose config
96+
docker compose build
97+
docker compose up -d
98+
```
99+
100+
Then validate:
101+
102+
```bash
103+
curl http://localhost:3000
104+
curl http://localhost:3000/tasks
105+
```
106+
107+
For CRUD-related changes, also validate:
108+
109+
```text
110+
POST /tasks
111+
GET /tasks
112+
PUT /tasks/:id
113+
DELETE /tasks/:id
114+
```
115+
116+
Finally:
117+
118+
```bash
119+
docker compose down
120+
```
121+
122+
## Database Changes
123+
124+
Database initialization is located in:
125+
126+
```text
127+
db/init.sql
128+
```
129+
130+
Remember that PostgreSQL initialization scripts execute only when the database volume is first created.
131+
132+
When testing schema changes:
133+
134+
```bash
135+
docker compose down -v
136+
docker compose up --build
137+
```
138+
139+
Never run destructive volume commands automatically without explicitly explaining that local data will be deleted.
140+
141+
## CI/CD
142+
143+
Docker CI should remain owned by this repository.
144+
145+
The preferred pipeline is:
146+
147+
```text
148+
Pull Request
149+
|
150+
v
151+
Validate Compose
152+
|
153+
v
154+
Build API image
155+
|
156+
v
157+
Start stack
158+
|
159+
v
160+
Smoke test API
161+
```
162+
163+
For `main`:
164+
165+
```text
166+
main
167+
|
168+
v
169+
Build image
170+
|
171+
v
172+
Publish
173+
|
174+
v
175+
GitHub Container Registry
176+
```
177+
178+
The resulting image is intended for downstream deployment by `kubernetes-task-manager`.
179+
180+
## Scope
181+
182+
Good changes for this repository include:
183+
184+
* API endpoints
185+
* validation
186+
* tests
187+
* Dockerfile optimization
188+
* Docker Compose improvements
189+
* health checks
190+
* smoke tests
191+
* GitHub Actions
192+
* GHCR publishing
193+
* database changes
194+
* application logging
195+
* security improvements
196+
197+
Out-of-scope changes include:
198+
199+
* Kubernetes manifests
200+
* cluster provisioning
201+
* Helm charts
202+
* Kubernetes Secrets
203+
* Kubernetes Services
204+
* Kubernetes Deployments
205+
206+
Those belong in `kubernetes-task-manager`.
207+
208+
## Documentation
209+
210+
When architecture or startup behavior changes, update:
211+
212+
* `README.md` for project-level information
213+
* `SETUP.md` for local setup or troubleshooting
214+
* `AGENTS.md` when agent behavior or repository boundaries change

0 commit comments

Comments
 (0)