Installation

Installation & Setup

SPARQLWorks™ is a web-based application that requires no traditional installation. This guide explains how to access and set up SPARQLWorks for optimal use.

🌐 Accessing SPARQLWorks

Online Access

SPARQLWorks is available as a hosted web application at:

https://sparqlworks.openlinksw.com/

Quick Start:

1. Open your web browser
2. Navigate to the SPARQLWorks URL
3. Start querying immediately

Browser Requirements

Supported Browsers:

• Chrome: 80+ (recommended)
• Firefox: 75+
• Safari: 13+
• Edge: 80+
• Mobile: iOS Safari 13+, Chrome Mobile 80+

Required Features:

• JavaScript enabled
• Local Storage support
• Modern CSS support
• HTTPS support (for OAuth authentication)

🏠 Self-Hosting Options

Option 1: Static Web Server

SPARQLWorks can be hosted on any static web server.

Using Python:

# Python 3.x
python -m http.server 8000
# Access at http://localhost:8000

Using Node.js:

npx serve .
# Access at http://localhost:3000

Using Apache/Nginx:

# .htaccess for Apache
<IfModule mod_headers.c>
    Header always set Access-Control-Allow-Origin "*"
    Header always set Access-Control-Allow-Methods "GET, POST, OPTIONS"
    Header always set Access-Control-Allow-Headers "Content-Type, Authorization"
</IfModule>

Option 2: GitHub Pages

Deploy SPARQLWorks to GitHub Pages for free hosting:

1. Fork the repository
2. Enable GitHub Pages in repository settings
3. Set source to main branch
4. Access at https://yourusername.github.io/sparqlworks/

Option 3: CDN Deployment

Host SPARQLWorks on a CDN for global distribution:

Netlify:

• Connect GitHub repository
• Automatic deployments
• Custom domains supported

Vercel:

• GitHub integration
• Edge network deployment
• Serverless functions if needed

🔧 Configuration

Environment Setup

No build process required! SPARQLWorks is a single HTML file with:

• Inline JavaScript: No external JS files to manage
• CDN dependencies: D3.js, Tailwind CSS, Ace Editor
• Self-contained: All code in one file

HTTPS Requirements

For OAuth authentication, SPARQLWorks must be served over HTTPS:

Development HTTPS:

# Using mkcert for local development
mkcert -install
mkcert localhost
# Serve with HTTPS certificate

Production HTTPS:

• Use SSL/TLS certificates
• Configure web server for HTTPS
• Redirect HTTP to HTTPS

🌍 Network Configuration

CORS Setup

SPARQL endpoints must allow cross-origin requests:

Endpoint CORS Headers:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization, Accept

Proxy Configuration

For endpoints without CORS support:

nginx Proxy Example:

location /sparql-proxy/ {
    proxy_pass https://your-endpoint.com/;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Apache Proxy:

ProxyPass /sparql-proxy/ https://your-endpoint.com/
ProxyPassReverse /sparql-proxy/ https://your-endpoint.com/

🔐 Authentication Setup

OAuth Configuration

For endpoints requiring OAuth authentication:

1. Register Client Application:

   • Client ID from endpoint administrator
   • Redirect URI: https://your-domain.com/sparqlworks.html

2. Configure Settings:

   • Open SPARQLWorks OAuth settings
   • Enter Client ID and Redirect URI
   • Save configuration

Bearer Token Setup

For simple token authentication:

1. Obtain Token: From endpoint administrator
2. Enter Token: In SPARQLWorks account menu
3. Validate: Test connection to endpoint

📱 Mobile Access

Progressive Web App

SPARQLWorks can be installed as a PWA:

Installation:

1. Open in mobile browser
2. Tap "Add to Home Screen"
3. Launch from home screen icon

Features:

• Offline interface loading
• App-like experience
• Push notifications (future)
• Native app integration

Touch Optimization

Mobile Interactions:

• Tap: Select nodes and edges
• Pinch: Zoom in/out
• Drag: Pan graph view
• Long press: Context menus

🏢 Enterprise Deployment

Corporate Environment

Requirements:

• Internal web server
• HTTPS certificates
• CORS-enabled endpoints
• Authentication integration

Deployment Steps:

1. Host on internal server
2. Configure SSL certificates
3. Set up endpoint proxies if needed
4. Configure OAuth for corporate identity
5. Distribute to users

Docker Deployment

FROM nginx:alpine
COPY sparqlworks.html /usr/share/nginx/html/index.html
COPY nginx.conf /etc/nginx/nginx.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

Docker Compose:

version: '3.8'
services:
  sparqlworks:
    image: nginx:alpine
    ports:
      - "8080:80"
    volumes:
      - ./sparqlworks.html:/usr/share/nginx/html/index.html
      - ./nginx.conf:/etc/nginx/nginx.conf

🔧 Development Setup

Local Development

Prerequisites:

• Modern web browser
• Text editor or IDE
• Local web server (optional)

Development Steps:

1. Clone repository
2. Open sparqlworks.html in browser
3. Make changes to HTML file
4. Test in browser
5. Deploy changes

Testing Endpoints

Local SPARQL Endpoint:

# Using Apache Jena Fuseki
docker run -p 3030:3030 -e ADMIN_PASSWORD=admin stain/jena-fuseki
# Access at http://localhost:3030

Sample Data Loading:

# Load RDF data
curl -X POST -H "Content-Type: text/turtle" \
  --data-binary @data.ttl \
  http://localhost:3030/$/datasets/mydata/data

🌐 Multi-Environment Setup

Development Environment

• Local endpoints for testing
• Debug logging enabled
• Development OAuth clients

Staging Environment

• Test endpoints with production data
• Production OAuth configuration
• User acceptance testing

Production Environment

• Production SPARQL endpoints
• Secure OAuth configuration
• Monitoring and logging
• High availability setup

📊 Monitoring and Maintenance

Access Logs

Monitor SPARQLWorks usage:

log_format sparqlworks '$remote_addr - $remote_user [$time_local] '
                       '"$request" $status $body_bytes_sent '
                       '"$http_referer" "$http_user_agent"';

access_log /var/log/nginx/sparqlworks.log sparqlworks;

Performance Monitoring

Track application performance:

• Page load times
• Query execution times
• Graph rendering performance
• Memory usage patterns

Updates and Maintenance

Update Process:

1. Download latest version
2. Test in staging environment
3. Deploy to production
4. Monitor for issues
5. Update documentation

🆘 Troubleshooting Installation

Common Issues

"Application won't load"

• Check JavaScript is enabled
• Verify modern browser version
• Check network connectivity
• Clear browser cache

"HTTPS required for OAuth"

• Configure SSL certificates
• Use HTTPS URLs
• Check certificate validity

"CORS errors"

• Configure endpoint CORS headers
• Use proxy configuration
• Check endpoint CORS policy

"Authentication fails"

• Verify OAuth configuration
• Check redirect URIs
• Validate client credentials
• Confirm HTTPS setup

Debug Mode

Enable debug logging:

// In browser console
localStorage.setItem('sparqlworks.debug', 'true');
location.reload();

Performance Issues

Optimization Tips:

• Use CDN for static assets
• Configure compression
• Set appropriate cache headers
• Monitor resource usage

📞 Support

Getting Help

• Documentation: Check all documentation pages
• Issues: Report bugs on project repository
• Community: Check community forums
• Enterprise: Contact OpenLink Software support

Diagnostic Information

When reporting installation issues, include:

• Web server configuration
• Browser console errors
• Network request details
• SPARQL endpoint information
• Authentication setup details

---

← Home | Next: User Guide →