grain.social is a photo sharing platform built on atproto.
grain.social
1# Grain Social
2
3A social photo-sharing platform built on the [AT Protocol](https://atproto.com),
4allowing users to create and share photo galleries.
5
6## Overview
7
8Grain Social is a photo-sharing platform designed specifically for the AT
9Protocol ecosystem. It enables users to:
10
11- Upload and organize photos into galleries
12- Share galleries with other users
13- Favorite galleries from other users
14- View photos in a customizable interface with both masonry and justified
15 layouts
16
17## Features
18
19- **Photo Management**: Upload, organize, and add alt text to photos
20- **Gallery Creation**: Create themed collections of your photos
21- **Custom Layouts**: View galleries in either masonry or justified grid layouts
22- **Social Features**: Follow users and favorite galleries
23- **Profile Management**: Create and customize your profile
24
25## Technology Stack
26
27- Built with [BFF](https://github.com/bigmoves/bff) (An AT Protocol Backend for
28 Frontend Framework)
29- Uses AT Protocol for identity and data persistence
30- Deno runtime
31- Written in TypeScript with JSX templating
32- HTMX for dynamic interactions
33- Hyperscript for enhanced client-side functionality
34- Tailwind CSS for styling
35
36## Development
37
38### Prerequisites
39
40- [Deno](https://deno.land/manual/getting_started/installation) Version 2.2.6 or
41 above
42- An AT Protocol account ([Bluesky](https://bsky.app))
43
44### Environment Variables
45
46```bash
47# .env
48BFF_DATABASE_URL=grain.db # SQLite db file
49BFF_JETSTREAM_URL=wss://jetstream1.us-west.bsky.network
50PDS_HOST_URL=https://ansel.grainsocial.network
51USE_CDN=true # Use bsky cdn
52```
53
54### Running Locally
55
56```bash
57# Backfill all network data
58deno run sync
59
60# Start the development server
61deno run dev
62```
63
64### Running the whole infra locally PDS + PLC + Jetstream
65
66You must ensure that pds.dev.grain.social resolves to your local machine
67(typically 127.0.0.1 or your Docker host).
68
69#### Add to /etc/hosts (macOS/Linux)
70
71```bash
72sudo nano /etc/hosts
73```
74
75```bash
76127.0.0.1 pds.dev.grain.social
77127.0.0.1 plc.dev.grain.social
78127.0.0.1 jetstream.dev.grain.social
79```
80
81#### Start services
82
83```bash
84cd local-infra
85docker compose up -d
86```
87
88#### Install the root certificate on your machine
89
90Copy the cert out:
91
92```bash
93docker cp caddy:/data/pki/authorities/grain/root.crt ./grain-root.crt
94```
95
96Once you have grain-root.crt, install it:
97
98macOS:
99
100```bash
101sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain grain-root.crt
102```
103
104Ubuntu/Linux:
105
106```bash
107sudo cp grain-root.crt /usr/local/share/ca-certificates/grain.crt
108sudo update-ca-certificates
109```
110
111#### Update ENV Variables
112
113Make sure the following env vars are in your .env
114
115```bash
116# for running local infra only
117BFF_DATABASE_URL=grain.db
118BFF_PLC_DIRECTORY_URL=https://plc.dev.grain.social
119BFF_JETSTREAM_URL=https://jetstream.dev.grain.social
120PDS_HOST_URL=https://pds.dev.grain.social
121DENO_TLS_CA_STORE=system
122USE_CDN=false
123```
124
125#### Run the app
126
127Start the app:
128
129```bash
130deno run dev
131```
132
133You can then create an account via the "Create Account" button in the navbar.
134
135After clicking the link, verify you are redirected to
136`https://pds.dev.grain.social/...`
137
138Create an account with your desired handle.
139
140If all goes well you will be redirectly to the app at
141`http://localhost:8080/onboard` and prompted to edit your profile details.
142
143From then on, you can login by typing `https://pds.dev.grain.social` into the
144login input and follow the PDS prompts to login.
145
146NOTE: When running with local-infra, only blobs on the local PDS will get
147resolved because of the PLC directory. All of the other images will appear
148broken. We could do some more work to support both but seems fine for now to
149test new features. Just switch back to non local-infra mode and you'll see them
150all.
151
152#### Explore records
153
154You can use [PDSls](https://pdsls.dev/) to explore records when running
155local-infra. Click the settings icon and change the PLC directory to
156`https://plc.dev.grain.social`.
157
158## License
159
160[MIT License](LICENSE)
161
162## Credits
163
164Developed by Chad Miller