Skip to content

Commit d1626a3

Browse files
pippinlovesdotpippinlovesdot
committed
v1.3.1: Deployment Documentation
- Added Dockerfile for universal container deployments - Added docs/ folder with deployment guides: - deployment.md: General requirements and overview - railway.md: Step-by-step Railway deployment guide - render.md: Render deployment guide - vps.md: VPS deployment guide (DigitalOcean, Linode, etc.) - api-keys.md: How to obtain Twitter API and OpenRouter keys
1 parent 617f376 commit d1626a3

File tree

6 files changed

+712
-0
lines changed

6 files changed

+712
-0
lines changed

‎Dockerfile‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
FROM python:3.11-slim
2+
3+
WORKDIR /app
4+
5+
# Install dependencies
6+
COPY requirements.txt .
7+
RUN pip install --no-cache-dir -r requirements.txt
8+
9+
# Copy application code
10+
COPY . .
11+
12+
# Create assets directory if not exists
13+
RUN mkdir -p assets
14+
15+
# Expose port (set via PORT env var)
16+
EXPOSE 8080
17+
18+
# Run the application
19+
CMD ["python", "main.py"]

‎docs/api-keys.md‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
# Getting API Keys
2+
3+
This guide explains how to obtain the required API keys for running your Twitter Agent.
4+
5+
## Twitter API Keys
6+
7+
### Step 1: Create Developer Account
8+
9+
1. Go to [developer.twitter.com](https://developer.twitter.com)
10+
2. Sign in with your Twitter account
11+
3. Apply for developer access (if not already approved)
12+
13+
### Step 2: Create a Project and App
14+
15+
1. Go to Developer Portal → Projects & Apps
16+
2. Click "Create Project"
17+
3. Fill in project details:
18+
- Project name: e.g., "My Twitter Agent"
19+
- Use case: Select appropriate option
20+
4. Create an App within the project
21+
22+
### Step 3: Get API Keys
23+
24+
In your App settings, you'll find:
25+
26+
| Key | Location | Description |
27+
|-----|----------|-------------|
28+
| `TWITTER_API_KEY` | Keys and tokens → API Key | Also called Consumer Key |
29+
| `TWITTER_API_SECRET` | Keys and tokens → API Secret | Also called Consumer Secret |
30+
| `TWITTER_BEARER_TOKEN` | Keys and tokens → Bearer Token | For read-only requests |
31+
| `TWITTER_ACCESS_TOKEN` | Keys and tokens → Access Token | For posting tweets |
32+
| `TWITTER_ACCESS_SECRET` | Keys and tokens → Access Token Secret | For posting tweets |
33+
34+
### Step 4: Set Permissions
35+
36+
1. Go to App settings → User authentication settings
37+
2. Click "Set up"
38+
3. Configure:
39+
- App permissions: **Read and write**
40+
- Type of App: **Web App, Automated App or Bot**
41+
- Callback URL: `https://example.com` (placeholder)
42+
- Website URL: Your website or Twitter profile
43+
4. Save and regenerate tokens if needed
44+
45+
### Important Notes
46+
47+
- **Free tier** allows posting but NOT reading mentions
48+
- **Basic tier** ($100/month) required for mention replies
49+
- Keep your keys secret - never commit them to git
50+
51+
---
52+
53+
## OpenRouter API Key
54+
55+
OpenRouter provides access to multiple LLM and image generation models through a single API.
56+
57+
### Step 1: Create Account
58+
59+
1. Go to [openrouter.ai](https://openrouter.ai)
60+
2. Sign up with Google/GitHub or email
61+
62+
### Step 2: Add Credits
63+
64+
1. Go to Account → Credits
65+
2. Add credits (minimum $5 recommended to start)
66+
3. Enable auto-recharge if desired
67+
68+
### Step 3: Generate API Key
69+
70+
1. Go to [openrouter.ai/keys](https://openrouter.ai/keys)
71+
2. Click "Create Key"
72+
3. Name it (e.g., "Twitter Agent")
73+
4. Copy the key (starts with `sk-or-v1-...`)
74+
75+
### Models Used
76+
77+
The agent uses these models by default:
78+
79+
| Purpose | Model | ~Cost per call |
80+
|---------|-------|----------------|
81+
| Text Generation | `anthropic/claude-sonnet-4` | ~$0.003-0.01 |
82+
| Image Generation | `google/gemini-2.0-flash-exp:free` | Free |
83+
84+
### Cost Estimate
85+
86+
Typical monthly costs with default settings (posting every 30 min):
87+
88+
- ~1,440 posts/month
89+
- ~$5-15/month on OpenRouter
90+
- Image generation is free with Gemini
91+
92+
---
93+
94+
## PostgreSQL Database
95+
96+
### Option 1: Railway (Recommended)
97+
98+
Railway automatically provisions PostgreSQL and sets `DATABASE_URL`.
99+
100+
### Option 2: Supabase
101+
102+
1. Go to [supabase.com](https://supabase.com)
103+
2. Create new project
104+
3. Go to Settings → Database
105+
4. Copy the "Connection string" (URI format)
106+
107+
Format: `postgresql://postgres:[PASSWORD]@db.[PROJECT].supabase.co:5432/postgres`
108+
109+
### Option 3: Neon
110+
111+
1. Go to [neon.tech](https://neon.tech)
112+
2. Create account and project
113+
3. Copy the connection string from dashboard
114+
115+
### Option 4: Self-hosted
116+
117+
See [vps.md](vps.md) for PostgreSQL setup on your own server.
118+
119+
---
120+
121+
## Environment Variables Summary
122+
123+
```bash
124+
# Twitter API
125+
TWITTER_API_KEY=your_api_key
126+
TWITTER_API_SECRET=your_api_secret
127+
TWITTER_ACCESS_TOKEN=your_access_token
128+
TWITTER_ACCESS_SECRET=your_access_secret
129+
TWITTER_BEARER_TOKEN=your_bearer_token
130+
131+
# OpenRouter
132+
OPENROUTER_API_KEY=sk-or-v1-...
133+
134+
# Database
135+
DATABASE_URL=postgresql://user:pass@host:5432/dbname
136+
137+
# Bot Settings
138+
POST_INTERVAL_MINUTES=30
139+
MENTIONS_INTERVAL_MINUTES=20
140+
ENABLE_IMAGE_GENERATION=true
141+
```
142+
143+
## Security Best Practices
144+
145+
1. **Never commit keys to git** - use `.env` files
146+
2. **Use environment variables** on hosting platforms
147+
3. **Rotate keys** periodically
148+
4. **Use separate keys** for development and production
149+
5. **Monitor usage** on OpenRouter dashboard

‎docs/deployment.md‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
# Deployment Guide
2+
3+
This guide covers deploying the Twitter Agent Bot to various platforms.
4+
5+
## Requirements
6+
7+
### System Requirements
8+
- Python 3.11+
9+
- PostgreSQL database
10+
- Persistent storage for assets (reference images)
11+
12+
### Environment Variables
13+
14+
All platforms require these environment variables:
15+
16+
```bash
17+
# OpenRouter API (LLM + Image Generation)
18+
OPENROUTER_API_KEY=sk-or-...
19+
20+
# Twitter API v2 credentials
21+
TWITTER_API_KEY=...
22+
TWITTER_API_SECRET=...
23+
TWITTER_ACCESS_TOKEN=...
24+
TWITTER_ACCESS_SECRET=...
25+
TWITTER_BEARER_TOKEN=...
26+
27+
# PostgreSQL Database
28+
DATABASE_URL=postgresql://user:pass@host:5432/dbname
29+
30+
# Bot Settings (optional, defaults shown)
31+
POST_INTERVAL_MINUTES=30
32+
MENTIONS_INTERVAL_MINUTES=20
33+
ENABLE_IMAGE_GENERATION=true
34+
```
35+
36+
See [api-keys.md](api-keys.md) for how to obtain these keys.
37+
38+
## Platform Guides
39+
40+
| Platform | Difficulty | Cost | Guide |
41+
|----------|------------|------|-------|
42+
| Railway | Easy | $5+/mo | [railway.md](railway.md) |
43+
| Render | Easy | $7+/mo | [render.md](render.md) |
44+
| VPS | Medium | $5+/mo | [vps.md](vps.md) |
45+
46+
## Quick Start (Railway)
47+
48+
1. Fork this repository
49+
2. Create Railway project from GitHub
50+
3. Add PostgreSQL database
51+
4. Set environment variables
52+
5. Deploy
53+
54+
See [railway.md](railway.md) for detailed steps.
55+
56+
## Database Setup
57+
58+
The bot automatically creates required tables on first run:
59+
60+
```sql
61+
-- Posts table
62+
CREATE TABLE posts (
63+
id SERIAL PRIMARY KEY,
64+
text TEXT NOT NULL,
65+
tweet_id VARCHAR(50),
66+
include_picture BOOLEAN DEFAULT FALSE,
67+
created_at TIMESTAMP DEFAULT NOW()
68+
);
69+
70+
-- Mentions table
71+
CREATE TABLE mentions (
72+
id SERIAL PRIMARY KEY,
73+
tweet_id VARCHAR(50) UNIQUE,
74+
author_handle VARCHAR(50),
75+
author_text TEXT,
76+
our_reply TEXT,
77+
action VARCHAR(20),
78+
tools_used TEXT,
79+
created_at TIMESTAMP DEFAULT NOW()
80+
);
81+
82+
-- Bot state table
83+
CREATE TABLE bot_state (
84+
key VARCHAR(50) PRIMARY KEY,
85+
value TEXT,
86+
updated_at TIMESTAMP DEFAULT NOW()
87+
);
88+
```
89+
90+
## Reference Images
91+
92+
Place character reference images in the `assets/` folder for consistent image generation.
93+
94+
Supported formats: `.png`, `.jpg`, `.jpeg`, `.jfif`, `.gif`, `.webp`
95+
96+
## Health Check
97+
98+
The bot exposes these endpoints:
99+
100+
- `GET /` - Basic status
101+
- `GET /health` - Health check
102+
- `GET /metrics` - Bot statistics
103+
- `GET /tier-status` - Twitter API tier info
104+
105+
## Twitter API Tiers
106+
107+
| Feature | Free | Basic ($100/mo) | Pro |
108+
|---------|------|-----------------|-----|
109+
| Post tweets | Yes | Yes | Yes |
110+
| Read mentions | No | Yes | Yes |
111+
| Rate limits | 50/day | 100/day | 300/day |
112+
113+
The bot automatically detects your tier and disables unavailable features.

0 commit comments

Comments
 (0)