Skip to content

Commit 96efdcb

Browse files
erinhmclarkerinhmclark
authored
Merge pull request #281 from bellingcat/add_inst_api_script
Add InstagrAPI server script to be used with the Instagram API Extractor.
2 parents 1d18399 + dd7d85b commit 96efdcb

File tree

7 files changed

+417
-2
lines changed

7 files changed

+417
-2
lines changed

‎docs/source/how_to/run_instagrapi_server.md

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
# InstagrAPI Server
2+
3+
The instagram API Extractor requires access to a running instance of the InstagrAPI server.
4+
We have a lightweight script with the endpoints required for our Instagram API Extractor module which you can run locally, or via Docker.
5+
6+
7+
8+
⚠️ Warning: Remember that it's best not to use your own personal account for archiving. [Here's why](../installation/authentication.md#recommendations-for-authentication).
9+
## Quick Start: Using Docker
10+
11+
We've provided a convenient shell script (`run_instagrapi_server.sh`) that simplifies the process of setting up and running the Instagrapi server in Docker. This script handles building the Docker image, setting up credentials, and starting the container.
12+
13+
### 🔧 Running the script:
14+
15+
Run this script either from the repository root or from within the `scripts/instagrapi_server` directory:
16+
17+
```bash
18+
./scripts/instagrapi_server/run_instagrapi_server.sh
19+
```
20+
21+
This script will:
22+
- Prompt for your Instagram username and password.
23+
- Create the necessary `.env` file.
24+
- Build the Docker image.
25+
- Start the Docker container and authenticate with Instagram, creating a session automatically.
26+
27+
### ⏱ To run the server again later:
28+
```bash
29+
docker start ig-instasrv
30+
```
31+
32+
### 🐛 Debugging:
33+
View logs:
34+
```bash
35+
docker logs ig-instasrv
36+
```
37+
38+
39+
### Overview: How the Setup Works
40+
41+
1. You enter your Instagram credentials in a local `.env` file
42+
2. You run the server **once locally** to generate a session file
43+
3. After that, you can choose to run the server again locally or inside Docker without needing to log in again
44+
45+
---
46+
47+
## Optional: Manual / Local Setup
48+
49+
If you'd prefer to run the server manually (without Docker), you can follow these steps:
50+
51+
52+
1. **Navigate to the server folder (and stay there for the rest of this guide)**:
53+
```bash
54+
cd scripts/instagrapi_server
55+
```
56+
57+
2. **Create a `secrets/` folder** (if it doesn't already exist in `scripts/instagrapi_server`):
58+
```bash
59+
mkdir -p secrets
60+
```
61+
62+
3. **Create a `.env` file** inside `secrets/` with your Instagram credentials:
63+
```dotenv
64+
INSTAGRAM_USERNAME="your_username"
65+
INSTAGRAM_PASSWORD="your_password"
66+
```
67+
68+
4. **Install dependencies** using the pyproject.toml file:
69+
70+
```bash
71+
poetry install --no-root
72+
```
73+
74+
5. **Run the server locally**:
75+
```bash
76+
poetry run uvicorn src.instaserver:app --port 8000
77+
```
78+
79+
6. **Watch for the message**:
80+
```
81+
Login successful, session saved.
82+
```
83+
84+
✅ Your session is now saved to `secrets/instagrapi_session.json`.
85+
86+
### To run it again locally:
87+
```bash
88+
poetry run uvicorn src.instaserver:app --port 8000
89+
```
90+
91+
---
92+
93+
## Adding the API Endpoint to Auto Archiver
94+
95+
The server should now be running within that session, and accessible at http://127.0.0.1:8000
96+
97+
You can set this in the Auto Archiver orchestration.yaml file like this:
98+
```yaml
99+
instagram_api_extractor:
100+
api_endpoint: http://127.0.0.1:8000
101+
```
102+
103+
104+
---
105+
106+
## 2. Running the Server Again
107+
108+
Once the session file is created, you should be able to run the server without logging in again.
109+
110+
### To run it locally (from scripts/instagrapi_server):
111+
```bash
112+
poetry run uvicorn src.instgrapinstance.instaserver:app --port 8000
113+
```
114+
115+
---
116+
117+
## 3. Running via Docker (After Setup is Complete, either locally or via the script)
118+
119+
Once the `instagrapi_session.json` and `.env` files are set up, you can pass them Docker and it should authenticate successfully.
120+
121+
### 🔨 Build the Docker image manually:
122+
```bash
123+
docker build -t instagrapi-server .
124+
```
125+
126+
### ▶️ Run the container:
127+
```bash
128+
docker run -d \
129+
--env-file secrets/.env \
130+
-v "$(pwd)/secrets:/app/secrets" \
131+
-p 8000:8000 \
132+
--name ig-instasrv \
133+
instagrapi-server
134+
```
135+
136+
This passes the /secrets/ directory to docker as well as the environment variables from the `.env` file.
137+
138+
139+
140+
---
141+
142+
## 4. Optional Cleanup
143+
144+
- **Stop the Docker container**:
145+
```bash
146+
docker stop ig-instasrv
147+
```
148+
149+
- **Remove the container**:
150+
```bash
151+
docker rm ig-instasrv
152+
```
153+
154+
- **Remove the Docker image**:
155+
```bash
156+
docker rmi instagrapi-server
157+
```
158+
159+
### ⏱ To run again later:
160+
```bash
161+
docker start ig-instasrv
162+
```
163+
164+
---
165+
166+
## Notes
167+
168+
- Never share your `.env` or `instagrapi_session.json` — these contain sensitive login data.
169+
- If you want to reset your session, simply delete the `secrets/instagrapi_session.json` file and re-run the local server.

‎scripts/instagrapi_server/.gitignore

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
secrets*
2+
*instagrapi_session.json

‎scripts/instagrapi_server/Dockerfile

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
FROM python:3.12-slim
2+
WORKDIR /app
3+
4+
# Install Poetry
5+
RUN pip install --upgrade pip
6+
RUN pip install poetry
7+
8+
# Copy all source code
9+
COPY . .
10+
11+
# Prevent Poetry from creating a virtual environment
12+
RUN poetry config virtualenvs.create false
13+
14+
# Install dependencies
15+
RUN poetry install --no-root
16+
17+
18+
# Use uvicorn to run the FastAPI app
19+
CMD ["poetry", "run", "uvicorn", "src.instaserver:app", "--host", "0.0.0.0", "--port", "8000"]

‎scripts/instagrapi_server/pyproject.toml

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
[project]
2+
name = "instaserver"
3+
version = "0.1.0"
4+
description = "A FastAPI InstagrAPI server"
5+
package-mode = false
6+
requires-python = ">=3.10"
7+
dependencies = [
8+
"fastapi (>=0.115.12,<0.116.0)",
9+
"instagrapi (>=2.1.3,<3.0.0)",
10+
"uvicorn (>=0.34.0,<0.35.0)",
11+
"pillow (>=11.1.0,<12.0.0)",
12+
"python-dotenv (>=1.1.0,<2.0.0)"
13+
]
14+
15+
16+
[build-system]
17+
requires = ["poetry-core>=2.0.0,<3.0.0"]
18+
build-backend = "poetry.core.masonry.api"

‎scripts/instagrapi_server/run_instagrapi_server.sh

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
#!/usr/bin/env bash
2+
#
3+
# run_instagrapi_server.sh
4+
# Usage:
5+
# From repo root: ./scripts/instagrapi_server/run_instagrapi_server.sh
6+
# Or from script dir: ./run_instagrapi_server.sh
7+
#
8+
9+
set -e
10+
11+
# Step 1: cd to the script's directory (contains Dockerfile and secrets/)
12+
cd "$(dirname "$0")" || exit 1
13+
14+
# Create secrets/ if it doesn't exist
15+
if [[ ! -d "secrets" ]]; then
16+
echo "Creating secrets/ directory..."
17+
mkdir secrets
18+
fi
19+
20+
echo "Enter your Instagram credentials to store in secrets/.env"
21+
read -rp "Instagram Username: " IGUSER
22+
read -rsp "Instagram Password: " IGPASS
23+
echo ""
24+
25+
cat <<EOF > secrets/.env
26+
INSTAGRAM_USERNAME=$IGUSER
27+
INSTAGRAM_PASSWORD=$IGPASS
28+
EOF
29+
echo "Created secrets/.env with your credentials."
30+
31+
# Build Docker image
32+
IMAGE_NAME="instagrapi-server"
33+
echo "Building Docker image '$IMAGE_NAME'..."
34+
docker build -t "$IMAGE_NAME" .
35+
36+
# Run container
37+
CONTAINER_NAME="ig-instasrv"
38+
echo "Running container '$CONTAINER_NAME'..."
39+
docker run -d \
40+
--env-file secrets/.env \
41+
-v "$(pwd)/secrets:/app/secrets" \
42+
-p 8000:8000 \
43+
--name "$CONTAINER_NAME" \
44+
"$IMAGE_NAME"
45+
46+
echo "Done! Instagrapi server is running on port 8000."
47+
echo "Use 'docker logs $CONTAINER_NAME' to view logs."
48+
echo "Use 'docker stop $CONTAINER_NAME' and 'docker rm $CONTAINER_NAME' to stop/remove the container."

0 commit comments

Comments
 (0)