137 lines
3.3 KiB
Markdown
137 lines
3.3 KiB
Markdown
# Quick Start Guide
|
|
|
|
## TL;DR - Get Started in 30 Seconds
|
|
|
|
```bash
|
|
# 1. Create .env file with your AWS credentials path
|
|
cat > .env << EOF
|
|
AWS_CONFIG_PATH=$HOME/.aws
|
|
PUID=$(id -u)
|
|
PGID=$(id -g)
|
|
EOF
|
|
|
|
# 2. Start the container
|
|
docker-compose up --build
|
|
# or with Podman:
|
|
podman-compose up --build
|
|
|
|
# 3. Open browser to http://localhost:5000
|
|
|
|
# 4. Select AWS profiles, enter MFA codes, and import!
|
|
```
|
|
|
|
## Container Setup (Recommended)
|
|
|
|
The easiest way to run SGO is using Docker or Podman. Works on Linux, macOS, and Windows.
|
|
|
|
### Prerequisites
|
|
|
|
Install either:
|
|
- **Docker**: https://docs.docker.com/get-docker/
|
|
- **Podman**: https://podman.io/getting-started/installation
|
|
|
|
### Setup Steps
|
|
|
|
1. **Create environment configuration:**
|
|
|
|
```bash
|
|
# Copy the example file
|
|
cp .env.example .env
|
|
|
|
# Edit with your settings
|
|
nano .env # or your preferred editor
|
|
```
|
|
|
|
Or create it manually:
|
|
|
|
```bash
|
|
cat > .env << EOF
|
|
AWS_CONFIG_PATH=$HOME/.aws
|
|
PUID=$(id -u)
|
|
PGID=$(id -g)
|
|
EOF
|
|
```
|
|
|
|
2. **Start the application:**
|
|
|
|
```bash
|
|
# Docker
|
|
docker-compose up --build
|
|
|
|
# Podman
|
|
podman-compose up --build
|
|
```
|
|
|
|
3. **Access the application:**
|
|
|
|
Open your browser to `http://localhost:5000`
|
|
|
|
### Import Data via GUI
|
|
|
|
1. Open your browser to `http://localhost:5000`
|
|
2. You'll see the **Import Page** with all your AWS profiles
|
|
3. **Select profiles**: Check the AWS accounts you want to import
|
|
4. **Enter MFA codes**: Paste your MFA/OTP codes for profiles that require authentication
|
|
5. **Click "Start Import"**: Watch real-time progress as data is fetched **in parallel**
|
|
6. **Auto-redirect**: When complete, you're taken to the Explorer
|
|
|
|
**Parallel Import**: All selected profiles are imported simultaneously in separate threads, so total time is the max of any single import, not the sum. This prevents MFA timeout issues.
|
|
|
|
### Explore Your Data
|
|
|
|
- Search for EC2 instances and Security Groups
|
|
- View detailed information
|
|
- Inspect security group rules
|
|
- Filter and search using regex
|
|
- Export data to CSV
|
|
|
|
### Refresh Data
|
|
|
|
- Click the **Refresh Data** button to refresh data using cached AWS sessions (valid for 55 minutes)
|
|
- Click the **Change Profiles** button to switch to different AWS accounts
|
|
|
|
## Local Python Setup
|
|
|
|
If you prefer to run without containers:
|
|
|
|
### 1. Install Dependencies
|
|
|
|
```bash
|
|
python3 -m venv venv
|
|
source venv/bin/activate # On Windows: venv\Scripts\activate
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
### 2. Start the Application
|
|
|
|
```bash
|
|
python app.py
|
|
```
|
|
|
|
### 3. Open Browser
|
|
|
|
Navigate to `http://localhost:5000`
|
|
|
|
## Stopping the Application
|
|
|
|
```bash
|
|
# Stop with Ctrl+C, or:
|
|
docker-compose down # Docker
|
|
podman-compose down # Podman
|
|
|
|
# To also remove the data volume:
|
|
docker-compose down -v
|
|
```
|
|
|
|
## Important Notes
|
|
|
|
- **⚠️ LOCAL USE ONLY**: Never expose this application to the internet. It has no authentication and provides access to sensitive AWS data.
|
|
- **Database Persistence**: When using containers, the database persists in a Docker volume or `./data` directory
|
|
- **Session Caching**: AWS sessions are cached for 55 minutes, allowing multiple refreshes without re-authentication
|
|
- **Parallel Import**: All selected AWS accounts are imported simultaneously for maximum speed
|
|
|
|
## Next Steps
|
|
|
|
- [Configuration Options](Configuration.md) - Customize your setup
|
|
- [AWS Configuration](AWS-Configuration.md) - Set up MFA and AWS profiles
|
|
- [Usage Guide](Usage.md) - Learn how to use SGO features
|