ywatanabe / test-5 / / /

No commits yet

01_GUIDE_INSTALLATION.md • 8.6 KB

Raw

Installation Guide

Complete installation instructions for SciTeX Writer for different environments and use cases.

Quick Start
System Requirements
Installation Methods
Native Installation (Recommended)
Container-Based
HPC/Cluster Environments
Verification
Troubleshooting

Quick Start

# 1. Clone or download the repository
git clone https://github.com/ywatanabe1989/scitex-writer.git
cd scitex-writer

# 2. Run compilation (auto-checks dependencies)
./scripts/shell/compile_manuscript.sh

# 3. If dependencies missing, install suggested packages and retry

System Requirements

Minimum Requirements

OS: Linux, macOS, or Windows (WSL2)
Bash: 4.0+
LaTeX: TeX Live 2020+ or equivalent

Core Dependencies

Package	Purpose	Ubuntu/Debian	macOS
`texlive-latex-extra`	LaTeX core + packages	`apt-get install`	`brew install texlive`
`latexdiff`	Diff PDF generation	`apt-get install`	`brew install latexdiff`
`parallel`	Parallel job execution	`apt-get install`	`brew install parallel`
`imagemagick`	Image format conversion	`apt-get install`	`brew install imagemagick`
`ghostscript`	PDF manipulation	`apt-get install`	`brew install ghostscript`

Optional Dependencies

Package	Purpose	When Needed
`python3-pip`	Python package manager	Python integration
`flask`	Web framework	GUI editor (`pip install scitex-writer[editor]`)
`git-lfs`	Large file storage	Binary assets in git
`docker`	Container runtime	Docker-based workflows
`singularity`	Container runtime	HPC environments

Installation Methods

Native Installation (Recommended)

Best for: Local development, personal use, standard Linux/macOS systems

Ubuntu/Debian (Fastest)

# 1. Update package manager
sudo apt-get update

# 2. Install core dependencies
sudo apt-get install texlive-latex-extra latexdiff parallel imagemagick ghostscript

# 3. Clone repository
git clone https://github.com/ywatanabe1989/scitex-writer.git
cd scitex-writer

# 4. Test compilation
./scripts/shell/compile_manuscript.sh

Expected output:

INFO: =========================
INFO: Dependency Check
INFO: =========================
INFO: ✓ All dependencies found
...
SUCC: TOTAL COMPILATION TIME: 15s

macOS

# 1. Install Homebrew (if not already installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 2. Install dependencies
brew install texlive latexdiff parallel imagemagick ghostscript

# 3. Clone repository
git clone https://github.com/ywatanabe1989/scitex-writer.git
cd scitex-writer

# 4. Test compilation
./scripts/shell/compile_manuscript.sh

Windows (WSL2)

# 1. Enable WSL2 (Windows Terminal as Admin)
wsl --install
wsl --install Ubuntu-22.04

# 2. Open Ubuntu terminal and run Ubuntu instructions above
sudo apt-get update
sudo apt-get install texlive-latex-extra latexdiff parallel imagemagick ghostscript
git clone https://github.com/ywatanabe1989/scitex-writer.git
cd scitex-writer
./scripts/shell/compile_manuscript.sh

Container-Based

Best for: Guaranteed consistency, CI/CD, no local setup needed

Docker

# 1. Build image (optional, pulls pre-built by default)
docker build -t scitex-writer:latest .

# 2. Run container
docker run --rm -v $(pwd):/work scitex-writer:latest \
  ./scripts/shell/compile_manuscript.sh

# 3. View output
ls -la manuscript.pdf

docker-compose.yml example:

version: '3'
services:
  scitex:
    image: scitex-writer:latest
    volumes:
      - .:/work
    command: ./scripts/shell/compile_manuscript.sh

GUI Editor via Docker:

# Build GUI image (includes Flask + LaTeX)
docker build -f scripts/containers/Dockerfile.gui -t scitex-writer-gui .

# Run (opens on http://localhost:5050)
docker run --rm -p 5050:5050 -v $(pwd):/workspace scitex-writer-gui

Singularity (HPC)

# 1. Build Singularity image
singularity build scitex-writer.sif docker://ywatanabe1989/scitex-writer:latest

# 2. Run compilation
singularity exec scitex-writer.sif ./scripts/shell/compile_manuscript.sh

# 3. Or bind to local directory
singularity run --bind $(pwd):/work scitex-writer.sif

HPC/Cluster Environments

Best for: Scientific computing clusters, job schedulers (SLURM, PBS)

Using Module System

# 1. Load TeX module (cluster-specific)
module load texlive/2023  # or similar
module load latexdiff
module load parallel

# 2. Clone repository
git clone https://github.com/ywatanabe1989/scitex-writer.git
cd scitex-writer

# 3. Compile
./scripts/shell/compile_manuscript.sh

SLURM Job Submission

#!/bin/bash
#SBATCH --job-name=scitex
#SBATCH --ntasks=1
#SBATCH --cpus-per-task=4
#SBATCH --time=00:30:00
#SBATCH --output=slurm-%j.log

module load texlive latexdiff parallel

cd /path/to/scitex-writer
./scripts/shell/compile_manuscript.sh

Submit with:

sbatch submit_job.sh

Using Singularity on HPC

#!/bin/bash
#SBATCH --job-name=scitex
#SBATCH --ntasks=1
#SBATCH --cpus-per-task=4

singularity exec /path/to/scitex-writer.sif \
  ./scripts/shell/compile_manuscript.sh

Verification

Test Basic Functionality

# 1. Check dependency availability
./scripts/shell/compile_manuscript.sh --help

# 2. Run dependency check (no compilation)
./scripts/shell/modules/check_dependancy_commands.sh

# 3. Test with sample manuscript
./scripts/shell/compile_manuscript.sh

# 4. Check output
ls -lah 01_manuscript/manuscript.pdf

# 5. Test GUI editor (optional)
pip install scitex-writer[editor]
scitex-writer gui --help

Expected Results

After successful installation:

✓ PDF compiled: 01_manuscript/manuscript.pdf
✓ Diff generated: 01_manuscript/manuscript_diff.pdf
✓ Logs created: scripts/shell/.compile_manuscript.sh.log
✓ Compilation time: ~15-30 seconds (first run)
                    ~5-10 seconds (subsequent runs with caching)

Run Test Suite

# Run all tests
./tests/run_all_tests.sh

Troubleshooting

Common Issues

Issue: "command not found: pdflatex"

Solution: Install LaTeX

# Ubuntu/Debian
sudo apt-get install texlive-latex-extra

# macOS
brew install texlive

# Verify
which pdflatex  # Should show path

Issue: "latexdiff: command not found"

Solution: Install latexdiff

# Ubuntu/Debian
sudo apt-get install latexdiff

# macOS
brew install latexdiff

# Verify
latexdiff --version

Issue: "parallel: command not found"

Solution: Install GNU parallel

# Ubuntu/Debian
sudo apt-get install parallel

# macOS
brew install parallel

# Verify
parallel --version

Issue: "Logs are empty" or "Output not captured"

Solution: Check log directory permissions

# Make logs directory writable
chmod 755 scripts/shell/
touch scripts/shell/.compile_manuscript.sh.log
chmod 644 scripts/shell/.compile_manuscript.sh.log

# Re-run compilation
./scripts/shell/compile_manuscript.sh

Issue: "Container not found" or "Singularity image error"

Solution: Pull/build container

# Docker
docker pull ywatanabe1989/scitex-writer:latest

# Singularity
singularity pull scitex-writer.sif docker://ywatanabe1989/scitex-writer:latest

Getting Help

If you encounter issues:

Check logs: cat scripts/shell/.compile_manuscript.sh.log
Run dependency check: ./scripts/shell/modules/check_dependancy_commands.sh
Check documentation: Read relevant guide in docs/
Report issue: https://github.com/ywatanabe1989/scitex-writer/issues
Include in report:
OS and version
LaTeX version: pdflatex --version
Bash version: bash --version
Full error message and logs

Next Steps

After successful installation:

Quick Start: Read 01_GUIDE_QUICK_START.md
Content Creation: See 01_GUIDE_CONTENT_CREATION.md
Bibliography Management: Check 01_GUIDE_BIBLIOGRAPHY.md
Architecture Details: Review 02_ARCHITECTURE_IMPLEMENTATION.md

Version Information

Tested on:
Ubuntu 20.04, 22.04, 24.04
macOS 12+
Windows 11 (WSL2)
CentOS/RHEL 7+
LaTeX: TeX Live 2020+ recommended
Python: 3.8+ for Python API
Last Updated: 2025-11-10

# Installation Guide
Complete installation instructions for SciTeX Writer for different environments and use cases.
## Table of Contents
- [Quick Start](#quick-start)
- [System Requirements](#system-requirements)
- [Installation Methods](#installation-methods)
  - [Native Installation (Recommended)](#native-installation-recommended)
  - [Container-Based](#container-based)
  - [HPC/Cluster Environments](#hpccluster-environments)
- [Verification](#verification)
- [Troubleshooting](#troubleshooting)
---
## Quick Start
```bash
# 1. Clone or download the repository
git clone https://github.com/ywatanabe1989/scitex-writer.git
cd scitex-writer
# 2. Run compilation (auto-checks dependencies)
./scripts/shell/compile_manuscript.sh
# 3. If dependencies missing, install suggested packages and retry
```
---
## System Requirements
### Minimum Requirements
- **OS**: Linux, macOS, or Windows (WSL2)
- **Bash**: 4.0+
- **LaTeX**: TeX Live 2020+ or equivalent
### Core Dependencies
| Package | Purpose | Ubuntu/Debian | macOS |
|---------|---------|---------------|-------|
| `texlive-latex-extra` | LaTeX core + packages | `apt-get install` | `brew install texlive` |
| `latexdiff` | Diff PDF generation | `apt-get install` | `brew install latexdiff` |
| `parallel` | Parallel job execution | `apt-get install` | `brew install parallel` |
| `imagemagick` | Image format conversion | `apt-get install` | `brew install imagemagick` |
| `ghostscript` | PDF manipulation | `apt-get install` | `brew install ghostscript` |
### Optional Dependencies
| Package | Purpose | When Needed |
|---------|---------|------------|
| `python3-pip` | Python package manager | Python integration |
| `flask` | Web framework | GUI editor (`pip install scitex-writer[editor]`) |
| `git-lfs` | Large file storage | Binary assets in git |
| `docker` | Container runtime | Docker-based workflows |
| `singularity` | Container runtime | HPC environments |
---
## Installation Methods
### Native Installation (Recommended)
**Best for**: Local development, personal use, standard Linux/macOS systems
#### Ubuntu/Debian (Fastest)
```bash
# 1. Update package manager
sudo apt-get update
# 2. Install core dependencies
sudo apt-get install texlive-latex-extra latexdiff parallel imagemagick ghostscript
# 3. Clone repository
git clone https://github.com/ywatanabe1989/scitex-writer.git
cd scitex-writer
# 4. Test compilation
./scripts/shell/compile_manuscript.sh
```
**Expected output**:
```
INFO: =========================
INFO: Dependency Check
INFO: =========================
INFO: ✓ All dependencies found
...
SUCC: TOTAL COMPILATION TIME: 15s
```
#### macOS
```bash
# 1. Install Homebrew (if not already installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# 2. Install dependencies
brew install texlive latexdiff parallel imagemagick ghostscript
# 3. Clone repository
git clone https://github.com/ywatanabe1989/scitex-writer.git
cd scitex-writer
# 4. Test compilation
./scripts/shell/compile_manuscript.sh
```
#### Windows (WSL2)
```bash
# 1. Enable WSL2 (Windows Terminal as Admin)
wsl --install
wsl --install Ubuntu-22.04
# 2. Open Ubuntu terminal and run Ubuntu instructions above
sudo apt-get update
sudo apt-get install texlive-latex-extra latexdiff parallel imagemagick ghostscript
git clone https://github.com/ywatanabe1989/scitex-writer.git
cd scitex-writer
./scripts/shell/compile_manuscript.sh
```
---
### Container-Based
**Best for**: Guaranteed consistency, CI/CD, no local setup needed
#### Docker
```bash
# 1. Build image (optional, pulls pre-built by default)
docker build -t scitex-writer:latest .
# 2. Run container
docker run --rm -v $(pwd):/work scitex-writer:latest \
  ./scripts/shell/compile_manuscript.sh
# 3. View output
ls -la manuscript.pdf
```
**docker-compose.yml** example:
```yaml
version: '3'
services:
  scitex:
    image: scitex-writer:latest
    volumes:
      - .:/work
    command: ./scripts/shell/compile_manuscript.sh
```
**GUI Editor via Docker**:
```bash
# Build GUI image (includes Flask + LaTeX)
docker build -f scripts/containers/Dockerfile.gui -t scitex-writer-gui .
# Run (opens on http://localhost:5050)
docker run --rm -p 5050:5050 -v $(pwd):/workspace scitex-writer-gui
```
#### Singularity (HPC)
```bash
# 1. Build Singularity image
singularity build scitex-writer.sif docker://ywatanabe1989/scitex-writer:latest
# 2. Run compilation
singularity exec scitex-writer.sif ./scripts/shell/compile_manuscript.sh
# 3. Or bind to local directory
singularity run --bind $(pwd):/work scitex-writer.sif
```
---
### HPC/Cluster Environments
**Best for**: Scientific computing clusters, job schedulers (SLURM, PBS)
#### Using Module System
```bash
# 1. Load TeX module (cluster-specific)
module load texlive/2023  # or similar
module load latexdiff
module load parallel
# 2. Clone repository
git clone https://github.com/ywatanabe1989/scitex-writer.git
cd scitex-writer
# 3. Compile
./scripts/shell/compile_manuscript.sh
```
#### SLURM Job Submission
```bash
#!/bin/bash
#SBATCH --job-name=scitex
#SBATCH --ntasks=1
#SBATCH --cpus-per-task=4
#SBATCH --time=00:30:00
#SBATCH --output=slurm-%j.log
module load texlive latexdiff parallel
cd /path/to/scitex-writer
./scripts/shell/compile_manuscript.sh
```
Submit with:
```bash
sbatch submit_job.sh
```
#### Using Singularity on HPC
```bash
#!/bin/bash
#SBATCH --job-name=scitex
#SBATCH --ntasks=1
#SBATCH --cpus-per-task=4
singularity exec /path/to/scitex-writer.sif \
  ./scripts/shell/compile_manuscript.sh
```
---
## Verification
### Test Basic Functionality
```bash
# 1. Check dependency availability
./scripts/shell/compile_manuscript.sh --help
# 2. Run dependency check (no compilation)
./scripts/shell/modules/check_dependancy_commands.sh
# 3. Test with sample manuscript
./scripts/shell/compile_manuscript.sh
# 4. Check output
ls -lah 01_manuscript/manuscript.pdf
# 5. Test GUI editor (optional)
pip install scitex-writer[editor]
scitex-writer gui --help
```
### Expected Results
After successful installation:
```
✓ PDF compiled: 01_manuscript/manuscript.pdf
✓ Diff generated: 01_manuscript/manuscript_diff.pdf
✓ Logs created: scripts/shell/.compile_manuscript.sh.log
✓ Compilation time: ~15-30 seconds (first run)
                    ~5-10 seconds (subsequent runs with caching)
```
### Run Test Suite
```bash
# Run all tests
./tests/run_all_tests.sh
```
---
## Troubleshooting
### Common Issues
#### Issue: "command not found: pdflatex"
**Solution**: Install LaTeX
```bash
# Ubuntu/Debian
sudo apt-get install texlive-latex-extra
# macOS
brew install texlive
# Verify
which pdflatex  # Should show path
```
#### Issue: "latexdiff: command not found"
**Solution**: Install latexdiff
```bash
# Ubuntu/Debian
sudo apt-get install latexdiff
# macOS
brew install latexdiff
# Verify
latexdiff --version
```
#### Issue: "parallel: command not found"
**Solution**: Install GNU parallel
```bash
# Ubuntu/Debian
sudo apt-get install parallel
# macOS
brew install parallel
# Verify
parallel --version
```
#### Issue: "Logs are empty" or "Output not captured"
**Solution**: Check log directory permissions
```bash
# Make logs directory writable
chmod 755 scripts/shell/
touch scripts/shell/.compile_manuscript.sh.log
chmod 644 scripts/shell/.compile_manuscript.sh.log
# Re-run compilation
./scripts/shell/compile_manuscript.sh
```
#### Issue: "Container not found" or "Singularity image error"
**Solution**: Pull/build container
```bash
# Docker
docker pull ywatanabe1989/scitex-writer:latest
# Singularity
singularity pull scitex-writer.sif docker://ywatanabe1989/scitex-writer:latest
```
### Getting Help
If you encounter issues:
1. **Check logs**: `cat scripts/shell/.compile_manuscript.sh.log`
2. **Run dependency check**: `./scripts/shell/modules/check_dependancy_commands.sh`
3. **Check documentation**: Read relevant guide in `docs/`
4. **Report issue**: https://github.com/ywatanabe1989/scitex-writer/issues
5. **Include in report**:
   - OS and version
   - LaTeX version: `pdflatex --version`
   - Bash version: `bash --version`
   - Full error message and logs
---
## Next Steps
After successful installation:
1. **Quick Start**: Read [`01_GUIDE_QUICK_START.md`](01_GUIDE_QUICK_START.md)
2. **Content Creation**: See [`01_GUIDE_CONTENT_CREATION.md`](01_GUIDE_CONTENT_CREATION.md)
3. **Bibliography Management**: Check [`01_GUIDE_BIBLIOGRAPHY.md`](01_GUIDE_BIBLIOGRAPHY.md)
4. **Architecture Details**: Review [`02_ARCHITECTURE_IMPLEMENTATION.md`](02_ARCHITECTURE_IMPLEMENTATION.md)
---
## Version Information
- **Tested on**:
  - Ubuntu 20.04, 22.04, 24.04
  - macOS 12+
  - Windows 11 (WSL2)
  - CentOS/RHEL 7+
- **LaTeX**: TeX Live 2020+ recommended
- **Python**: 3.8+ for Python API
- **Last Updated**: 2025-11-10