Installation
This comprehensive guide covers everything you need to install, configure, and deploy Jowy Portfolio in both development and production environments.System Requirements
Minimum Requirements
- Node.js: 18.0.0 or higher
- Package Manager: npm, yarn, or pnpm
- Git: Latest stable version
- Operating System: macOS, Linux, or Windows (with WSL recommended)
Recommended Setup
- Node.js: 20.x LTS
- Package Manager: pnpm (for faster installs and better monorepo support)
- Editor: VS Code with Astro extension
- Terminal: iTerm2 (macOS), Windows Terminal, or similar
Local Development Setup
Configure Environment Variables
Create a Add the following environment variables:
.env file in the project root:.env
Obtaining API Credentials
Spotify API Setup
Spotify API Setup
- Go to Spotify Developer Dashboard
- Log in with your Spotify account
- Click Create an App
- Fill in app name and description
- Copy the Client ID and Client Secret
SoundCloud API Setup
SoundCloud API Setup
- Visit SoundCloud Developers
- Click Register a new app
- Provide app details
- Copy the Client ID
YouTube API Setup
YouTube API Setup
- Go to Google Cloud Console
- Create a new project or select existing
- Enable YouTube Data API v3
- Navigate to Credentials → Create Credentials → API Key
- Copy the API key
Google Calendar API (Optional)
Google Calendar API (Optional)
- In Google Cloud Console
- Enable Google Calendar API
- Create API credentials
- Make your calendar public or share with the service account
- Copy the Calendar ID from calendar settings
Start Development Server
Launch the development server:The server configuration from Expected output:
astro.config.mjs:14-17:The
host: true setting allows you to test on mobile devices via your local network IP.Verify Installation
Open http://localhost:4321 and verify:
- ✅ Landing page loads with neon animations
- ✅ Three sections visible: DJ, JOWY, Sound Designer
- ✅ Language switcher works (ES/EN)
- ✅ Dark mode is active
- ✅ No console errors
Production Deployment
Vercel Deployment (Recommended)
Jowy Portfolio is optimized for Vercel deployment with built-in analytics and edge functions.Connect to Vercel
- Visit Vercel Dashboard
- Click Add New Project
- Import your GitHub repository
- Vercel will auto-detect the Astro framework
Configure Environment Variables
In the Vercel project settings, add all environment variables from your
.env file:- Go to Settings → Environment Variables
- Add each variable individually
- Apply to Production, Preview, and Development environments
Deploy
Click Deploy to start the build process.Vercel will:
- Clone your repository
- Install dependencies
- Run
astro build - Deploy to edge network
package.json:7:Automated Weekly Rebuilds
Jowy Portfolio includes GitHub Actions workflow for automated weekly rebuilds, ensuring fresh content from external APIs.Setup CI/CD Pipeline
Get Vercel Deploy Hook
In Vercel project settings:
- Navigate to Settings → Git → Deploy Hooks
- Create a new hook named “Weekly Rebuild”
- Select the branch (usually
main) - Copy the generated webhook URL
Add GitHub Secret
In your GitHub repository:
- Go to Settings → Secrets and variables → Actions
- Click New repository secret
- Name:
VERCEL_DEPLOY_HOOK - Value: Paste the webhook URL from Vercel
- Click Add secret
Verify Workflow
The workflow is already configured in The schedule can be modified using crontab.guru.
.github/workflows/rebuild.yml:1-14:During each weekly rebuild, the build process fetches fresh data from Spotify, SoundCloud, YouTube, and Google Calendar APIs, keeping the site automatically updated.
Understanding the Caching System
Server-Side Cache Implementation
The caching system prevents excessive API calls and improves performance:Cache Duration by Service
Different services use different cache durations:| Service | Cache Duration | Location |
|---|---|---|
| Spotify Token | expires_in - 60s | src/server/services/spotify/auth.ts:42 |
| SoundCloud Tracks | 3600s (1 hour) | src/server/services/soundcloud/tracks.ts:8 |
| YouTube Playlist | 3600s (1 hour) | src/server/services/youtube/playlist.ts:7 |
Cache Keys
Cache keys are constructed to include parameters:BaseFetcher Pattern
All API calls go through theBaseFetcher abstraction:
Custom Error Types
The BaseFetcher uses custom error classes:Troubleshooting
Build fails with API errors
Build fails with API errors
If the build fails due to API errors:
- Verify all environment variables are set correctly
- Check API credentials are still valid
- Ensure API rate limits haven’t been exceeded
- Test API endpoints manually using curl or Postman
Port conflicts
Port conflicts
If port 4321 is already in use:
TypeScript errors
TypeScript errors
Ensure you’re using Node.js 18+:If using older Node.js:
Module resolution errors
Module resolution errors
The project uses path aliases defined in If imports fail, verify the alias is configured correctly.
tsconfig.json:Vercel deployment fails
Vercel deployment fails
Common Vercel deployment issues:
- Build command not found: Verify
package.jsonhasbuildscript - Environment variables missing: Double-check all vars are set in Vercel
- Node version mismatch: Add
.nvmrcorenginesinpackage.json:
Additional Configuration
Customizing Site Metadata
Update site information inastro.config.mjs:10:
Configuring Internationalization
Modify language settings ini18n.config.ts:1-4:
src/dictionaries/.
Adjusting Cache Durations
Modify cache durations in service files:Next Steps
Architecture Guide
Deep dive into the service layer, caching system, and BaseFetcher pattern
API Reference
Complete reference for all services and utility functions
For questions or issues, visit the GitHub repository to open an issue or discussion.