How to run your first TopicForge batch job locally

You can run TopicForge on your laptop to test your API integrations and voice profiles before deploying. This local setup lets you trigger batch jobs, verify editorial guardrails, and inspect the generated markdown payloads without using production resources.

This guide walks you through configuring the local services and triggering your first multi-stage article generation job.

Prerequisites and setting up MongoDB

The TopicForge architecture uses MongoDB to store job states, voice profiles, and generated article drafts. You need a running MongoDB instance before you start the application services.

The fastest way to start MongoDB locally is with Docker. Run this command in your terminal:

docker run -d -p 27017:27017 --name topicforge-mongo mongo:latest

If you do not use Docker, you can install the native MongoDB community edition on your machine. Make sure the service runs on the default port.

To verify your database is active, connect with MongoDB Compass or the mongosh CLI:

mongosh --host localhost --port 27017

Your local database must be accessible at mongodb://localhost:27017 before you start the other services.

Running the content-api service

The content-api service coordinates your programmatic SEO pipeline. It exposes the REST endpoints for managing jobs — it also stores your configuration settings and orchestrates the batch workflow.

To start the service, open a terminal window and navigate to your local content-api directory:

cd path/to/content-api
npm install

Once the dependencies install, start the service in development mode:

npm run dev

The service starts on http://localhost:3000 by default. The console log will confirm that the server is listening and connected to your local MongoDB database.

Running the ai-service

While content-api manages the orchestration, the ai-service handles the generation. This service connects to Gemini via Vertex AI. It processes the four distinct stages of our article pipeline — creating the outline, drafting the copy, applying the voice pass, and generating the final SEO metadata.

Open a separate terminal window, navigate to the ai-service directory, install the packages, and start the development server:

cd path/to/ai-service
npm install
npm run dev

The ai-service runs on http://localhost:3001. It listens for generation tasks sent by the content-api orchestrator. Both services must run at the same time for your batch jobs to process.

Configuring your local environment settings

Both services require specific environment variables to communicate, connect to MongoDB, and authenticate with Vertex AI. Create a .env file in the root of both the content-api and ai-service directories.

Here is the configuration for the content-api .env file:

PORT=3000
MONGODB_URI=mongodb://localhost:27017/topicforge_local
AI_SERVICE_URL=http://localhost:3001

Here is the configuration for the ai-service .env file:

PORT=3001
GCP_PROJECT_ID=your-gcp-project-id
GCP_API_KEY=your-gcp-api-key

Replace the placeholder Google Cloud Platform (GCP) values with your actual sandbox credentials. Do not commit these .env files to your version control system — add .env to your .gitignore file to keep your API keys secure.

Triggering your first batch job via the API

With MongoDB, content-api, and ai-service running, you can trigger your first local batch job. The platform uses a single POST request to generate multiple articles at the same time.

Send a POST request to the /v1/jobs endpoint using curl. This example payload requests two articles, defines a voice profile, and sets editorial guardrails to block specific words.

curl -X POST http://localhost:3000/v1/jobs \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Local Test Run",
    "topics": [
      {
        "title": "How to scale Postgres database reads",
        "keyword": "scale postgres reads"
      },
      {
        "title": "Understanding database sharding patterns",
        "keyword": "database sharding patterns"
      }
    ],
    "voiceProfile": {
      "tone": "pragmatic",
      "style": "direct",
      "bannedPhrases": [
        "in today’s digital landscape",
        "game-changer",
        "revolutionize"
      ]
    }
  }'

When you run this command, the content-api service validates the payload. It writes the initial job state to MongoDB and returns a JSON response with a unique job ID:

{
  "jobId": "job_67890abcde12345",
  "status": "pending",
  "totalTopics": 2,
  "createdAt": "2026-03-30T10:00:00.000Z"
}

The orchestrator then sends tasks to the ai-service. You can watch your terminal windows to see the services communicate. The ai-service processes each topic through the four-stage pipeline — applying your voice profile rules and generating the final markdown files, meta descriptions, and FAQ schemas.

If you want to run these workflows without managing local database instances, TopicForge offers a cloud-based API. You can pass your topics, voice profiles, and custom guidelines to our managed pipeline. Pricing is $10 for a single article, $49 for a 10-pack (about $4.90 per article), or $399 for a 100-pack (about $3.99 per article).

FAQs

Can I run the TopicForge local environment without Docker?

Yes. You can run all services using Node.js directly by running npm install and npm run dev in the service directories.

How do I verify that my local batch job completed successfully?

You can query the local MongoDB database directly — or you can send a GET request to the /v1/jobs/:id endpoint to check the status of your batch run.

Which AI models does the local setup use for generation?

The local ai-service connects to Gemini via Vertex AI to run the four-stage pipeline. This ensures your local output matches the production environment.