Skip to main content

Installation Guide

This guide will help you install and configure the Blog Marketing Platform for local development or production deployment.

System Requirements

Before you begin, ensure your system meets these requirements:
  • Node.js: Version 18.0 or higher
  • Package Manager: npm, pnpm, or yarn
  • Git: For cloning the repository
  • Modern Browser: Chrome, Firefox, Safari, or Edge
  • Operating System: macOS, Linux, or Windows
Recommended: Use pnpm for faster installations and better disk space efficiency.

Installation Methods

Choose the installation method that best fits your needs:
Perfect for development, testing, and contributing to the project.

Local Development Setup

Follow these steps to set up the platform for local development:
1

Clone the Repository

First, clone the repository to your local machine:
git clone https://github.com/yourusername/blog-marketing-platform.git
cd blog-marketing-platform
2

Install Dependencies

Install all required dependencies using your preferred package manager:
npm install
This will install all dependencies from package.json, including:
  • Astro 5.13.3
  • React 19.1.1
  • Zustand 5.0.8
  • Tailwind CSS 4.1.12
  • And all other required packages
3

Configure Environment Variables

Create your environment configuration file:
cp .env.example .env.local
Then edit .env.local with your configuration:
.env.local
# API Configuration
# Change the port according to your backend configuration (default 3000)
VITE_API_BASE_URL=http://localhost:3000/api/v1
VariableDescriptionDefault
VITE_API_BASE_URLBackend API base URLhttp://localhost:3000/api/v1
4

Start Development Server

Launch the development server:
npm run dev
The server will start at http://localhost:4321You should see output like:
🚀 astro v5.13.3 started in 45ms

┃ Local    http://localhost:4321/
┃ Network  use --host to expose
5

Verify Installation

Open your browser and navigate to http://localhost:4321You should see the landing page. Try accessing:
  • /auth/login - Login page
  • /auth/register - Registration page
  • /admin - Admin dashboard (after login)

Configuration Options

API Mode Configuration

The platform supports two modes: Mock Mode (default) and Real API Mode.
export const API_CONFIG = {
  USE_REAL_API: false, // Use mock data
  BASE_URL: API_BASE_URL,
  // ...
};
Mock Mode is perfect for:
  • Frontend development without backend dependency
  • UI/UX testing and demos
  • Learning the platform
Real API Mode requires:
  • Backend API running (see Backend Setup below)
  • Valid VITE_API_BASE_URL in .env.local

Astro Configuration

The platform uses Astro with these integrations:
astro.config.mjs
import { defineConfig } from 'astro/config';
import react from '@astrojs/react';
import sitemap from '@astrojs/sitemap';
import tailwindcss from '@tailwindcss/vite';
import vercel from '@astrojs/vercel/serverless';

export default defineConfig({
  site: 'https://your-domain.com',
  integrations: [
    react(),
    sitemap()
  ],
  output: 'static', // or 'server' for SSR
  vite: {
    plugins: [tailwindcss()],
    envPrefix: 'VITE_',
  },
  adapter: vercel({}),
});
  • site: Your production URL (used for sitemap generation)
  • integrations: React for components, sitemap for SEO
  • output: static for SSG, server for SSR
  • adapter: Deployment adapter (Vercel, Netlify, etc.)

Backend Setup

To use the platform with a real backend API:
1

Backend Requirements

The platform expects a RESTful API with these endpoints:
  • POST /auths/sign-in - User login
  • POST /auths/sign-up - User registration
  • POST /auths/sign-out - User logout
  • POST /auths/refresh - Token refresh
  • GET /posts - List posts
  • POST /posts - Create post
  • GET /categorias - List categories
  • GET /comentarios - List comments
  • And more… (see API documentation)
2

Start Backend Server

Follow your backend’s installation instructions to start the API server.Example for Node.js backend:
cd backend
npm install
npm run dev
Ensure it’s running on the port specified in VITE_API_BASE_URL (default: 3000)
3

Enable Real API Mode

Update the configuration to use the real API:
src/config/api.ts
export const API_CONFIG = {
  USE_REAL_API: true, // Change to true
  BASE_URL: API_BASE_URL,
  // ...
};
4

Test API Connection

Try logging in with real credentials or creating a new account.Check the browser console for API logs:
🔧 API Configuration:
  - VITE_API_BASE_URL: http://localhost:3000/api/v1
  - BASE_URL (resolved): http://localhost:3000/api/v1
  - USE_REAL_API: true

Build for Production

When you’re ready to deploy to production:
1

Build the Project

Create an optimized production build:
npm run build
This generates static files in the dist/ directory.
2

Preview Production Build

Test the production build locally:
npm run preview
This serves the dist/ folder at http://localhost:4321
3

Deploy to Hosting

Deploy the dist/ folder to your hosting provider:

Vercel

vercel deploy

Netlify

netlify deploy --prod

Custom Server

rsync -avz dist/ user@server:/var/www/

Docker

docker build -t blog-platform .
docker run -p 80:80 blog-platform

Project Structure

Understand the key directories and files:
/
├── public/              # Static assets (images, fonts)
├── src/
│   ├── components/      # React components
│   │   ├── admin/       # Admin dashboard components
│   │   ├── auth/        # Authentication components
│   │   ├── ui/          # Reusable UI components
│   │   └── editor/      # MDX editor components
│   ├── config/          # Configuration files
│   │   └── api.ts       # API configuration
│   ├── data/            # Mock data for development
│   ├── hooks/           # Custom React hooks
│   ├── layouts/         # Astro layouts
│   ├── lib/             # Utility libraries
│   │   └── apiClient.ts # HTTP client
│   ├── pages/           # Astro pages (routes)
│   ├── schemas/         # Zod validation schemas
│   ├── services/        # API service layer
│   ├── styles/          # Global styles
│   ├── types/           # TypeScript type definitions
│   └── env.d.ts         # Environment type definitions
├── .env.example         # Example environment variables
├── astro.config.mjs     # Astro configuration
├── package.json         # Project dependencies
├── tsconfig.json        # TypeScript configuration
└── tailwind.config.js   # Tailwind CSS configuration

Development Workflow

Authentication Flow

The platform uses JWT-based authentication:
// 1. User logs in
import { login } from './services/authService';

const { user, token } = await login({
  email: '[email protected]',
  password: 'password123'
});

// 2. Token stored in localStorage
localStorage.setItem('auth_token', token);
localStorage.setItem('user_data', JSON.stringify(user));

// 3. Token sent with all API requests
const headers = {
  'Authorization': `Bearer ${token}`,
  'Content-Type': 'application/json'
};

// 4. Auto-refresh on 401 errors
if (response.status === 401) {
  await attemptTokenRefresh();
}

State Management with Zustand

The platform uses Zustand for global state management:
// Example: Using the auth store
import { useAuthStore } from './stores/authStore';

const { user, isAuthenticated, login, logout } = useAuthStore();

// The store persists to localStorage automatically
if (isAuthenticated) {
  console.log('Current user:', user);
}

Troubleshooting

If port 4321 is already in use:
# Use a different port
astro dev --port 3000
Or update astro.config.mjs:
server: {
  port: 3000
}
If you’re getting API connection errors:
  1. Check VITE_API_BASE_URL in .env.local
  2. Verify backend is running: curl http://localhost:3000/api/v1/health
  3. Check CORS configuration in backend
  4. Look for errors in browser console
  5. Try switching to mock mode: USE_REAL_API: false
If you encounter build errors:
# Clear cache and rebuild
rm -rf node_modules/.astro
npm run build

# Check for TypeScript errors
npx astro check
If you see “Cannot find module” errors:
# Reinstall dependencies
rm -rf node_modules pnpm-lock.yaml
pnpm install

Available Scripts

Common commands for development and deployment:
CommandDescription
npm run devStart development server at localhost:4321
npm run buildBuild production bundle to ./dist/
npm run previewPreview production build locally
npm run astroRun Astro CLI commands
astro checkCheck for TypeScript and Astro errors
astro addAdd integrations (e.g., astro add react)

Next Steps

Now that you have the platform installed:

Quickstart Guide

Create your first blog post and explore features.

API Configuration

Connect to your backend and configure endpoints.

Customize Theme

Customize colors, fonts, and branding.

Deploy

Deploy to production with Vercel or Netlify.

Additional Resources

Installation complete! You’re ready to start building with Blog Marketing Platform.

Build docs developers (and LLMs) love