Skip to content

Commit 7033a09

Browse files
Golden-Eagle07Golden-Eagle07
committed
Updated worklfows and updated documents
1 parent 1f63f1a commit 7033a09

7 files changed

Lines changed: 268 additions & 68 deletions

File tree

‎.github/workflows/android-release.yaml‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
name: Build Apk and Release
2+
3+
on:
4+
push:
5+
tags:
6+
- 'v*'
7+
8+
env:
9+
REGISTRY: ghcr.io
10+
IMAGE_NAME: ${{ github.repository }}
11+
12+
jobs:
13+
apk:
14+
name: Flutter APK → GitHub Release
15+
runs-on: ubuntu-latest
16+
permissions:
17+
contents: write
18+
19+
steps:
20+
- name: Checkout source code
21+
uses: actions/checkout@v4
22+
23+
- name: Set up Java (required for Android builds)
24+
uses: actions/setup-java@v4
25+
with:
26+
distribution: temurin
27+
java-version: '17'
28+
29+
- name: Set up Flutter
30+
uses: subosito/flutter-action@v2
31+
with:
32+
channel: stable
33+
cache: true
34+
35+
- name: Install Flutter dependencies
36+
working-directory: mobile
37+
run: flutter pub get
38+
39+
- name: Run Flutter analyze
40+
working-directory: mobile
41+
run: flutter analyze --no-fatal-infos
42+
43+
- name: Build release APK
44+
working-directory: mobile
45+
run: flutter build apk --release
46+
47+
- name: Rename APK with version tag
48+
run: |
49+
mv mobile/build/app/outputs/flutter-apk/app-release.apk \
50+
mobile/build/app/outputs/flutter-apk/elephant-${{ github.ref_name }}.apk
51+
52+
- name: Create or update GitHub Release
53+
uses: softprops/action-gh-release@v2
54+
with:
55+
tag_name: ${{ github.ref_name }}
56+
name: Elephant ${{ github.ref_name }}
57+
draft: false
58+
prerelease: false
59+
generate_release_notes: true
60+
files: mobile/build/app/outputs/flutter-apk/elephant-${{ github.ref_name }}.apk
61+
env:
62+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

‎.github/workflows/backend.yaml‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,9 @@ name: Go Integration & Test Suite
22

33
on:
44
push:
5-
branches: [ main, v0.1.0 ]
5+
branches: [ main, v0.1.5, 0.2.0 ]
66
pull_request:
7-
branches: [ main, v0.1.0 ]
7+
branches: [ main ]
88

99
jobs:
1010
test:
@@ -63,14 +63,16 @@ jobs:
6363
run: |
6464
cd server
6565
sudo apt-get update && sudo apt-get install -y postgresql-client
66-
PGPASSWORD="${{ secrets.POSTGRES_PASSWORD }}" psql -h localhost -p "${{ vars.POSTGRES_PORT }}" -U "${{ vars.POSTGRES_USER }}" -d "${{ vars.POSTGRES_DB }}" \
66+
PGPASSWORD="${{ secrets.POSTGRES_PASSWORD }}" psql -h "${{ vars.POSTGRES_HOST }}" -p "${{ vars.POSTGRES_PORT }}" -U "${{ vars.POSTGRES_USER }}" -d "${{ vars.POSTGRES_DB }}" \
6767
-f migrations/001_create_users_up.sql \
6868
-f migrations/002_create_refresh_tokens_up.sql \
6969
-f migrations/003_add_search_indexes_up.sql \
70-
-f migrations/004_create_message_up.sql
70+
-f migrations/004_create_message_up.sql \
71+
-f migrations/005_create_message_status_up.sql\
72+
-f migrations/006_create_groups_table_up.sql
7173
go run main.go &
7274
for i in $(seq 1 10); do
73-
curl -sf http://localhost:${{ vars.PORT }}/api/health && break
75+
curl -sf http://${{ vars.POSTGRES_HOST }}:${{ vars.PORT }}/api/health && break
7476
echo "Waiting for server... attempt $i"
7577
sleep 2
7678
done

‎.github/workflows/release.yaml‎

Lines changed: 1 addition & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
name: Build & Publish Release
1+
name: Build image and release package
22

33
on:
44
push:
@@ -48,54 +48,3 @@ jobs:
4848
push: true
4949
tags: ${{ steps.meta.outputs.tags }}
5050
labels: ${{ steps.meta.outputs.labels }}
51-
52-
apk:
53-
name: Flutter APK → GitHub Release
54-
runs-on: ubuntu-latest
55-
permissions:
56-
contents: write
57-
58-
steps:
59-
- name: Checkout source code
60-
uses: actions/checkout@v4
61-
62-
- name: Set up Java (required for Android builds)
63-
uses: actions/setup-java@v4
64-
with:
65-
distribution: temurin
66-
java-version: '17'
67-
68-
- name: Set up Flutter
69-
uses: subosito/flutter-action@v2
70-
with:
71-
channel: stable
72-
cache: true
73-
74-
- name: Install Flutter dependencies
75-
working-directory: mobile
76-
run: flutter pub get
77-
78-
- name: Run Flutter analyze
79-
working-directory: mobile
80-
run: flutter analyze --no-fatal-infos
81-
82-
- name: Build release APK
83-
working-directory: mobile
84-
run: flutter build apk --release
85-
86-
- name: Rename APK with version tag
87-
run: |
88-
mv mobile/build/app/outputs/flutter-apk/app-release.apk \
89-
mobile/build/app/outputs/flutter-apk/elephant-${{ github.ref_name }}.apk
90-
91-
- name: Create or update GitHub Release
92-
uses: softprops/action-gh-release@v2
93-
with:
94-
tag_name: ${{ github.ref_name }}
95-
name: Elephant ${{ github.ref_name }}
96-
draft: false
97-
prerelease: false
98-
generate_release_notes: true
99-
files: mobile/build/app/outputs/flutter-apk/elephant-${{ github.ref_name }}.apk
100-
env:
101-
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

‎CODE_OF_CONDUCT.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
We endorse and follow the code of conduct of the International Olympiad of Informatics, available at the [IOI website](https://ioinformatics.org/page/code-of-conduct/50).

‎README.md‎

Lines changed: 164 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,165 @@
11
# Elephant
2-
Elephant – a privacy-first, open-source messenger.
2+
Elephant – a privacy-first, open-source messaging application made with Go and Flutter. Elephant supports secure authentication, user discovery, and real-time chat over WebSocket, with all communication TLS-protected between client and server.
3+
4+
## Quick Start (Docker/Podman)
5+
6+
The fastest way to run Elephant is by pulling the published image — no Go toolchain required.
7+
8+
```bash
9+
# Log in to GitHub Container Registry
10+
docker login ghcr.io -u YOUR_GITHUB_USERNAME
11+
# or: podman login ghcr.io -u YOUR_GITHUB_USERNAME
12+
13+
# Clone the repo for the compose file and .env template
14+
git clone https://github.com/commandlinecoding/elephant.git
15+
cd elephant
16+
17+
# Copy and fill in environment variables
18+
cp .env.example .env
19+
20+
# Start the stack
21+
docker compose up
22+
# or: podman-compose up
23+
```
24+
Once running, verify the server is healthy:
25+
26+
```bash
27+
curl http://localhost:8080/api/health
28+
```
29+
30+
You should see:
31+
32+
```json
33+
{"success":true,"data":{"postgres":"up","timestamp":"..."}}
34+
```
35+
36+
## Tech Stack
37+
38+
| Layer | Technology |
39+
|---|---|
40+
| Backend | Go (chi, pgx, gorilla/websocket, golang-jwt, argon2) |
41+
| Mobile | Flutter (http, web_socket_channel, provider, sqflite) |
42+
| Database | PostgreSQL 16 |
43+
| CI/CD | GitHub Actions, Docker Compose, GHCR |
44+
45+
## Local Development Setup
46+
47+
If you're contributing to the backend and want to build from source instead of pulling the published image, use the dev compose override:
48+
49+
```bash
50+
docker compose -f compose.yaml -f compose.dev.yaml up
51+
```
52+
53+
This builds the `server` image from `server/Dockerfile` on every run instead of pulling from GHCR, so your local changes are reflected immediately.
54+
55+
### Running the backend without Docker
56+
57+
```bash
58+
cd server
59+
go mod download
60+
go run main.go
61+
```
62+
63+
Make sure PostgreSQL is running and reachable using the values in your `.env` file (`POSTGRES_HOST`, `POSTGRES_PORT`, `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB`).
64+
65+
### Running database migrations
66+
67+
```bash
68+
cd server
69+
psql "postgres://$POSTGRES_USER:$POSTGRES_PASSWORD@$POSTGRES_HOST:$POSTGRES_PORT/$POSTGRES_DB" \
70+
-f migrations/001_create_users_up.sql \
71+
-f migrations/002_create_refresh_tokens_up.sql \
72+
-f migrations/003_add_search_indexes_up.sql \
73+
-f migrations/004_create_message_up.sql
74+
```
75+
76+
### Running the mobile app
77+
78+
```bash
79+
cd mobile
80+
flutter pub get
81+
flutter run
82+
```
83+
84+
## Environment Variables
85+
86+
| Variable | Description | Default |
87+
|---|---|---|
88+
| `HOST` | Server bind address | `127.0.0.1` |
89+
| `PORT` | Server port | `3000` |
90+
| `POSTGRES_USER` | Database username | `postgres` |
91+
| `POSTGRES_PASSWORD` | Database password | — |
92+
| `POSTGRES_DB` | Database name | `myapi_db` |
93+
| `POSTGRES_PORT` | Database port | `5432` |
94+
| `POSTGRES_HOST` | Database host | `localhost` |
95+
| `JWT_SECRET` | Secret key for signing JWTs | — |
96+
| `ARGON_MEMORY` | Argon2id memory cost (KB) | `65536` |
97+
| `ARGON_ITERATIONS` | Argon2id iteration count | `3` |
98+
| `ARGON_PARALLELISM` | Argon2id parallelism degree | `2` |
99+
100+
See `.env.example` for a starting template.
101+
102+
103+
## API
104+
105+
Checkout the [API document](docs/API_CONTRACTS.md)
106+
107+
### Registration note
108+
109+
Usernames are normalized to lowercase and assigned a random 4-digit discriminator on registration to avoid collisions, e.g. registering as `abc` may result in the stored username `abc.4821`. Use the full discriminated username returned in the registration response when logging in.
110+
111+
## Testing
112+
113+
Run the full backend test suite (unit + integration):
114+
115+
```bash
116+
cd server
117+
go vet ./...
118+
go test -v ./...
119+
```
120+
121+
Integration tests under [server/tests/](server/tests/) expect a running server and database. Start the stack first, then run:
122+
123+
```bash
124+
HOST=localhost PORT=8080 go test -v ./tests/...
125+
```
126+
127+
### CI/CD
128+
129+
Tests, `go vet`, and `staticcheck` run automatically on every push and pull request via GitHub Actions (`.github/workflows/`). Docker images are built and published to GHCR via manual `workflow_dispatch` or on tagged pushes.
130+
131+
## Project Structure
132+
133+
```
134+
elephant/
135+
├── .github/ # GitHub Actions workflows
136+
├── docs/ # Project documentation
137+
├── mobile/ # Flutter client
138+
│ ├── android/
139+
│ ├── ios/
140+
│ ├── lib/
141+
│ ├── assets/
142+
│ ├── pubspec.yaml
143+
│ └── README.md
144+
├── server/ # Go backend
145+
│ ├── config/ # DB, JWT, Argon2, CORS configuration
146+
│ ├── controllers/ # HTTP handlers
147+
│ ├── env/ # Environment variable loading
148+
│ ├── errors/ # Sentinel error definitions
149+
│ ├── middlewares/ # Auth, CORS, logging, rate limiting
150+
│ ├── migrations/ # SQL migration files
151+
│ ├── models/ # Data models
152+
│ ├── repository/ # Database access layer
153+
│ ├── routes/ # Route definitions
154+
│ ├── services/ # Business logic (auth, users, JWT, WebSocket hub)
155+
│ ├── tests/ # Integration tests
156+
│ └── Dockerfile
157+
├── compose.yaml # Default: pulls published image
158+
├── compose.dev.yaml # Override: builds server from source
159+
├── .env.example # Environment variable template
160+
└── LICENSE
161+
```
162+
163+
## License
164+
165+
See [LICENSE](LICENSE) for details.

‎SECURITY.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
Security Policy
2+
Reporting a Vulnerability
3+
4+
If you discover a security vulnerability in this repository, please report it using [GitHub's built-in reporting tool](https://github.com/CommandLineCoding/Elephant/security/advisories). We appreciate your efforts to responsibly disclose your findings and will make every effort to acknowledge your report promptly.
5+
6+
Thank you for helping to keep our project secure!

0 commit comments

Comments
 (0)