HED Web Tools — User Guide¶

Overview¶

HED Web Tools is a comprehensive web-based application for working with HED (Hierarchical Event Descriptors) data. This guide provides complete instructions for setting up, configuring, and deploying the application in various environments.

Note

This guide covers both development and production setups. Choose the section that matches your use case.

Table of Contents¶

Quick Start Options¶

Choose the setup method that best fits your needs:

🚀 Local Development Setup¶

Best for: Trying out the application, contributing to development, or testing

Time required: ~5 minutes

Prerequisites: Python 3.10+, Git

🐳 Production Docker Deployment¶

Best for: Production servers with Docker support

Time required: ~10 minutes

Prerequisites: Ubuntu Server, Docker, sudo access

📚 Documentation Development¶

Best for: Contributing to documentation or building docs locally

Time required: ~3 minutes

Prerequisites: Python 3.10+

Local Development Setup¶

Prerequisites¶

Ensure you have the following installed:

Python 3.10 or higher — Download Python
Git — Download Git
Command line access (Terminal, Command Prompt, or PowerShell)

Tip

On Windows, we recommend using PowerShell or the Windows Terminal for better command line experience.

Installation Steps¶

1. Clone the Repository¶

git clone https://github.com/hed-standard/hed-web
cd hed-web

2. Create Virtual Environment¶

Using a virtual environment isolates dependencies and prevents conflicts:

# Create virtual environment
python -m venv .venv

3. Activate Virtual Environment¶

Windows (PowerShell/Command Prompt):

.venv\Scripts\activate

macOS/Linux:

source .venv/bin/activate

Note

You’ll need to activate the virtual environment every time you work on the project in a new terminal session.

4. Install Dependencies¶

pip install -r requirements.txt

5. Create Configuration File¶

Windows:

copy config_template.py config.py

macOS/Linux:

cp config_template.py config.py

6. Run the Application¶

hedweb --host 127.0.0.1 --port 5000 --debug

7. Access the Application¶

Open your browser and navigate to: http://127.0.0.1:5000

Note

🎉 Success! The HED Web Tools application is now running locally.

Development Workflow¶

Once you have the application running:

Make changes to the code
Restart the server (Ctrl+C, then run hedweb again)
Refresh your browser to see changes
Run tests before committing (see Testing section)

Documentation Development¶

Setting Up Documentation Environment¶

1. Install Documentation Dependencies¶

pip install sphinx furo myst-parser

2. Build Documentation¶

cd docs
sphinx-build -b html . _build/html

3. Serve Documentation Locally¶

# Install live server (optional)
pip install sphinx-autobuild

# Serve with auto-reload
sphinx-autobuild . _build/html --open-browser

The documentation will be available at http://localhost:8000 and will automatically rebuild when you make changes.

Documentation Structure¶

docs/
├── conf.py              # Sphinx configuration
├── index.rst            # Main documentation index
├── introduction.md      # Introduction to HED
├── user_guide.md        # This file
└── api/                 # API documentation
    ├── index.md
    ├── architecture.md
    └── ...

Production Deployment¶

Docker Deployment (Recommended)¶

This method uses Docker for containerization and is suitable for most production environments.

Prerequisites¶

Ubuntu Server (18.04 or newer recommended)
Docker and Docker Compose installed
Sudo access
Domain name (optional but recommended)

Quick Production Setup¶

# Create deployment directory
mkdir -p ~/deploy_hed
cd ~/deploy_hed

# Download deployment script
curl -fsSL -o deploy.sh https://raw.githubusercontent.com/hed-standard/hed-web/main/deploy/deploy.sh

# Make script executable
chmod +x deploy.sh

# Run deployment (replace with your domain or IP)
sudo ./deploy.sh main prod your-domain.com

Manual Docker Setup¶

If you prefer manual setup or need customization:

Clone and prepare:

git clone https://github.com/hed-standard/hed-web
cd hed-web/deploy

Configure environment:

cp base_config.py config.py
# Edit config.py as needed

Build and run:

docker build -t hedweb .
docker run -d -p 33000:80 --name hedweb-container hedweb

The application will be available on port 33000.

Reverse Proxy Setup¶

For production deployments, you’ll typically want to use a reverse proxy like Nginx or Apache.

Nginx Configuration¶

Create /etc/nginx/sites-available/hedweb:

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://localhost:33000;
        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;
        
        # Handle large file uploads
        client_max_body_size 100M;
    }
}

Enable the site:

sudo ln -s /etc/nginx/sites-available/hedweb /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

SSL/TLS Setup with Certbot¶

# Install Certbot
sudo apt install certbot python3-certbot-nginx

# Get SSL certificate
sudo certbot --nginx -d your-domain.com

# Verify auto-renewal
sudo certbot renew --dry-run

Configuration Reference¶

Environment Variables¶

The application can be configured using environment variables:

Variable	Description	Default	Example
`HED_WEB_HOST`	Server host	`127.0.0.1`	`0.0.0.0`
`HED_WEB_PORT`	Server port	`5000`	`8080`
`HED_WEB_DEBUG`	Debug mode	`False`	`True`
`HED_WEB_SECRET_KEY`	Flask secret key	Generated	`your-secret-key`

Configuration File Options¶

Edit config.py to customize:

# Basic settings
HOST = '127.0.0.1'
PORT = 5000
DEBUG = True

# Security
SECRET_KEY = 'your-secret-key-here'
WTF_CSRF_ENABLED = True

# Upload settings
MAX_CONTENT_LENGTH = 16 * 1024 * 1024  # 16MB max file size

# HED schema settings
HED_CACHE_FOLDER = '/tmp/hed_cache'
DEFAULT_HED_VERSION = '8.2.0'

Testing¶

Running Tests¶

Unit Tests¶

python -m unittest discover -s tests/ -p 'test_*.py'

Service Tests¶

python -m unittest discover -s services_tests/ -p 'test_*.py'

Note

You must have a running instance of the application to run service tests.

Run All Tests¶

python -m unittest discover

Test with Coverage¶

pip install coverage
python -m coverage run --source=hedweb -m unittest discover
python -m coverage report
python -m coverage html

The coverage HTML report will be available in htmlcov/index.html.

Test Structure¶

tests/                  # Unit tests
├── test_*.py
└── data/              # Test data files

services_tests/        # Integration tests
├── test_services_*.py
└── data/              # Test data files

Troubleshooting¶

Common Issues¶

Issue: ModuleNotFoundError¶

Symptoms: ModuleNotFoundError: No module named 'hedweb'

Solution:

Ensure virtual environment is activated
Install requirements: pip install -r requirements.txt
Check Python version: python --version (should be 3.10+)

Issue: Port Already in Use¶

Symptoms: Address already in use error

Solution:

Use a different port: hedweb --port 5001

Or kill existing process:

# Find process using port 5000
netstat -tulpn | grep :5000
# Kill process by PID
kill -9 <PID>

Issue: Permission Denied (Linux/macOS)¶

Symptoms: Permission errors when running commands

Solution:

Check file permissions: ls -la
Make scripts executable: chmod +x script_name.sh
Use sudo only when necessary

Issue: Docker Container Won’t Start¶

Symptoms: Container exits immediately or fails to start

Solution:

Check logs: docker logs hedweb-container
Verify port availability: netstat -tulpn | grep :33000
Check configuration files
Ensure Docker daemon is running

Getting Debug Information¶

Application Logs¶

# Enable debug mode
export HED_WEB_DEBUG=True
hedweb --debug

System Information¶

# Python version
python --version

# Installed packages
pip list

# System info (Linux/macOS)
uname -a

# System info (Windows)
systeminfo

Performance Optimization¶

For Development¶

Use --debug flag for auto-reload
Disable unnecessary features in config
Use local HED schemas when possible

For Production¶

Set DEBUG = False in config
Use production WSGI server (gunicorn)
Enable caching
Use reverse proxy (Nginx/Apache)
Monitor resource usage

Getting Help¶

Documentation Resources¶

API Documentation: API Reference
HED Standard: https://www.hedtags.org/
GitHub Repository: https://github.com/hed-standard/hed-web

Community Support¶

GitHub Issues: Report bugs or request features
Discussions: Ask questions in GitHub Discussions
Email: Contact the HED team for enterprise support

Contributing¶

We welcome contributions! Please see:

CONTRIBUTING.md for development guidelines
CODE_OF_CONDUCT.md for community guidelines
Open issues for areas needing help

Appendix¶

Command Reference¶

Development Commands¶

# Start development server
hedweb --host 127.0.0.1 --port 5000 --debug

# Run tests
python -m unittest discover -s tests/ -p 'test_*.py'

# Build documentation
sphinx-build -b html docs docs/_build/html

# Install in development mode
pip install -e .

Production Commands¶

# Build Docker image
docker build -t hedweb .

# Run Docker container
docker run -d -p 33000:80 hedweb

# Check container status
docker ps

# View container logs
docker logs hedweb-container

File Structure Overview¶

hed-web/
├── hedweb/                    # Main application package
│   ├── __init__.py
│   ├── app_factory.py        # Flask application factory
│   ├── routes.py             # Web routes
│   └── ...                   # Other modules
├── docs/                     # Documentation
├── tests/                    # Unit tests
├── services_tests/           # Integration tests
├── deploy/                   # Deployment files
├── requirements.txt          # Python dependencies
├── config_template.py        # Configuration template
└── setup.py                  # Package setup