> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/go-gitea/gitea/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start Guide

> Get up and running with Gitea in 5 minutes - from installation to your first repository

## 5-Minute Quick Start

This guide will get you from zero to a working Gitea instance with your first repository in just 5 minutes.

<Note>
  This quick start uses Docker for the fastest setup. For other installation methods, see the [Installation Guide](/installation).
</Note>

## Prerequisites

Before you begin, ensure you have:

* **Docker installed** - [Get Docker](https://docs.docker.com/get-docker/)
* **Terminal/Command line access**
* **5 minutes of your time**

That's it! No other dependencies required.

## Step 1: Start Gitea

Run this single command to start Gitea:

```bash theme={null}
docker run -d \
  --name=gitea \
  -p 3000:3000 \
  -p 222:22 \
  -v gitea-data:/data \
  gitea/gitea:latest
```

<Info>
  **What this does:**

  * Downloads the latest Gitea Docker image
  * Starts Gitea on port 3000 (web interface)
  * Maps port 222 for SSH access
  * Creates a Docker volume for persistent data
</Info>

<Steps>
  <Step title="Wait for Gitea to start">
    Give it a few seconds to initialize. Check if it's running:

    ```bash theme={null}
    docker ps
    ```

    You should see the `gitea` container in the list.
  </Step>

  <Step title="Access the web interface">
    Open your browser and go to:

    ```text theme={null}
    http://localhost:3000
    ```

    You'll see the Gitea installation page.
  </Step>
</Steps>

## Step 2: Complete Initial Setup

Gitea will guide you through the initial configuration:

<Steps>
  <Step title="Configure database">
    The default SQLite configuration is perfect for getting started:

    * **Database Type**: SQLite3 (pre-selected)
    * **Path**: Default value is fine

    <Info>
      SQLite requires no additional setup and is perfect for small to medium installations. You can migrate to PostgreSQL or MySQL later if needed.
    </Info>
  </Step>

  <Step title="Configure basic settings">
    Adjust these settings for your environment:

    <Tabs>
      <Tab title="For Local Development">
        * **Server Domain**: `localhost`
        * **SSH Server Port**: `222`
        * **Gitea Base URL**: `http://localhost:3000/`

        <Note>
          Keep the defaults - they work great for local testing!
        </Note>
      </Tab>

      <Tab title="For Production/Remote Server">
        * **Server Domain**: Your domain or IP (e.g., `git.example.com`)
        * **SSH Server Port**: `222` (or `22` if not using Docker)
        * **Gitea Base URL**: `http://your-domain-or-ip:3000/`

        <Warning>
          Make sure to use your actual domain or IP address that users will use to access Gitea.
        </Warning>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Create administrator account">
    Scroll down to the "Administrator Account Settings" section:

    * **Administrator Username**: Choose your admin username (e.g., `admin`)
    * **Password**: Choose a strong password
    * **Email**: Your email address

    <Warning>
      Keep these credentials safe! This account has full control over your Gitea instance.
    </Warning>
  </Step>

  <Step title="Install Gitea">
    Click the **"Install Gitea"** button at the bottom of the page.

    The installation takes just a few seconds. You'll be redirected to the login page when complete.
  </Step>
</Steps>

## Step 3: Create Your First Repository

<Steps>
  <Step title="Log in to Gitea">
    Use the administrator credentials you just created to log in.
  </Step>

  <Step title="Create a new repository">
    Click the **"+"** icon in the top right corner and select **"New Repository"**.

    <Info>
      You can also click the green **"Create Repository"** button on your dashboard.
    </Info>
  </Step>

  <Step title="Configure your repository">
    Fill in the repository details:

    * **Owner**: Your username (pre-selected)
    * **Repository Name**: e.g., `my-first-repo`
    * **Description**: (optional) "My first Gitea repository"
    * **Visibility**: Choose Public or Private
    * **Initialize Repository**: Check this box
      * ✅ **Add .gitignore**: Select a template (optional)
      * ✅ **Add README**: Recommended for getting started
      * ✅ **Add License**: Choose a license (optional)

    Click **"Create Repository"** when ready.
  </Step>

  <Step title="Explore your repository">
    Congratulations! You now have your first Gitea repository.

    You'll see:

    * Your README.md file
    * Repository navigation (Code, Issues, Pull Requests, etc.)
    * Clone URL (HTTP and SSH)
  </Step>
</Steps>

## Step 4: Clone and Push Code

Now let's interact with your repository from the command line:

<Tabs>
  <Tab title="Using HTTPS">
    <Steps>
      <Step title="Clone the repository">
        Copy the HTTPS clone URL from your repository page and run:

        ```bash theme={null}
        git clone http://localhost:3000/admin/my-first-repo.git
        cd my-first-repo
        ```
      </Step>

      <Step title="Make changes">
        ```bash theme={null}
        echo "# Hello Gitea!" >> hello.md
        git add hello.md
        git commit -m "Add hello file"
        ```
      </Step>

      <Step title="Push changes">
        ```bash theme={null}
        git push origin main
        ```

        Enter your Gitea username and password when prompted.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Using SSH">
    <Steps>
      <Step title="Add SSH key to Gitea">
        First, generate an SSH key if you don't have one:

        ```bash theme={null}
        ssh-keygen -t ed25519 -C "your_email@example.com"
        ```

        Copy your public key:

        ```bash theme={null}
        cat ~/.ssh/id_ed25519.pub
        ```

        In Gitea:

        1. Click your avatar → **Settings**
        2. Go to **SSH / GPG Keys**
        3. Click **Add Key**
        4. Paste your public key and give it a name
        5. Click **Add Key**
      </Step>

      <Step title="Clone the repository">
        ```bash theme={null}
        git clone ssh://git@localhost:222/admin/my-first-repo.git
        cd my-first-repo
        ```

        <Note>
          Notice port 222 in the SSH URL - this matches the port we mapped in Docker.
        </Note>
      </Step>

      <Step title="Make and push changes">
        ```bash theme={null}
        echo "# Hello Gitea!" >> hello.md
        git add hello.md
        git commit -m "Add hello file"
        git push origin main
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

<Steps>
  <Step title="Verify your changes">
    Go back to your browser and refresh the repository page.

    You should see your new `hello.md` file!
  </Step>
</Steps>

## Step 5: Explore Gitea Features

Now that you have a working repository, explore what Gitea can do:

<CardGroup cols={2}>
  <Card title="Create an Issue" icon="clipboard-list">
    Try the issue tracker:

    1. Go to **Issues** tab
    2. Click **New Issue**
    3. Add a title and description
    4. Submit the issue
  </Card>

  <Card title="Make a Pull Request" icon="code-pull-request">
    Test the code review workflow:

    1. Create a new branch
    2. Make changes and push
    3. Create a pull request
    4. Review and merge
  </Card>

  <Card title="Add Collaborators" icon="users">
    Invite team members:

    1. Go to repository **Settings**
    2. Click **Collaborators**
    3. Add users and set permissions
  </Card>

  <Card title="Setup Webhooks" icon="webhook">
    Integrate with external services:

    1. Go to repository **Settings**
    2. Click **Webhooks**
    3. Add webhook URL
    4. Configure events
  </Card>
</CardGroup>

## Common Tasks

### Create an Organization

Organizations help manage multiple repositories and team members:

<Steps>
  <Step title="Create organization">
    Click the **"+"** icon → **New Organization**
  </Step>

  <Step title="Configure organization">
    * Set organization name and description
    * Choose visibility settings
    * Click **Create Organization**
  </Step>

  <Step title="Add team members">
    1. Go to organization **Teams**
    2. Create teams with different permissions
    3. Add members to teams
  </Step>
</Steps>

### Enable Gitea Actions (CI/CD)

<Note>
  Gitea Actions provides GitHub Actions-compatible CI/CD capabilities.
</Note>

<Steps>
  <Step title="Enable actions in repository">
    Go to repository **Settings** → **Actions** and enable Actions.
  </Step>

  <Step title="Create workflow file">
    Create `.gitea/workflows/test.yaml` in your repository:

    ```yaml theme={null}
    name: Test Workflow
    on: [push, pull_request]

    jobs:
      test:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v4
          - name: Run tests
            run: |
              echo "Running tests..."
              # Add your test commands here
    ```
  </Step>

  <Step title="Push and watch it run">
    Commit and push the workflow file. Check the **Actions** tab to see it run!
  </Step>
</Steps>

<Warning>
  For Actions to work, you need to set up an [Act Runner](https://docs.gitea.com/usage/actions/act-runner). The workflow will be queued until a runner is available.
</Warning>

### Configure Email Notifications

Enable email notifications for issues, pull requests, and more:

<Steps>
  <Step title="Edit configuration">
    Stop Gitea and edit the configuration file.

    For Docker:

    ```bash theme={null}
    docker stop gitea
    docker exec -it gitea sh
    vi /data/gitea/conf/app.ini
    ```
  </Step>

  <Step title="Add SMTP settings">
    Add these lines to `app.ini`:

    ```ini theme={null}
    [mailer]
    ENABLED = true
    FROM = gitea@example.com
    PROTOCOL = smtps
    SMTP_ADDR = smtp.example.com
    SMTP_PORT = 465
    USER = gitea@example.com
    PASSWD = your-password
    ```
  </Step>

  <Step title="Restart Gitea">
    ```bash theme={null}
    docker restart gitea
    ```
  </Step>
</Steps>

## Managing Your Gitea Instance

### Start/Stop/Restart Gitea

```bash theme={null}
# Check status
docker ps

# Stop Gitea
docker stop gitea

# Start Gitea
docker start gitea

# Restart Gitea
docker restart gitea

# View logs
docker logs gitea

# Follow logs in real-time
docker logs -f gitea
```

### Backup Your Data

<Warning>
  Always backup your data regularly!
</Warning>

```bash theme={null}
# Backup the Docker volume
docker run --rm \
  -v gitea-data:/data \
  -v $(pwd):/backup \
  alpine tar czf /backup/gitea-backup-$(date +%Y%m%d).tar.gz /data

# Or copy the entire volume
docker cp gitea:/data ./gitea-backup-$(date +%Y%m%d)
```

### Update Gitea

Keep your Gitea instance up to date:

```bash theme={null}
# Pull the latest image
docker pull gitea/gitea:latest

# Stop and remove the old container
docker stop gitea
docker rm gitea

# Start with the new image (use your original docker run command)
docker run -d \
  --name=gitea \
  -p 3000:3000 \
  -p 222:22 \
  -v gitea-data:/data \
  gitea/gitea:latest
```

<Info>
  Your data is safe in the Docker volume and will persist across container updates.
</Info>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Can't access Gitea at localhost:3000">
    **Check if container is running:**

    ```bash theme={null}
    docker ps
    ```

    **Check logs for errors:**

    ```bash theme={null}
    docker logs gitea
    ```

    **Verify port isn't already in use:**

    ```bash theme={null}
    lsof -i :3000
    ```
  </Accordion>

  <Accordion title="Git push asks for password every time">
    **Using HTTPS:**
    Set up credential helper:

    ```bash theme={null}
    git config --global credential.helper store
    ```

    **Or switch to SSH:**
    Add your SSH key to Gitea and use SSH clone URLs instead.
  </Accordion>

  <Accordion title="SSH connection refused">
    **Check SSH port mapping:**

    ```bash theme={null}
    docker port gitea
    ```

    **Test SSH connection:**

    ```bash theme={null}
    ssh -T git@localhost -p 222
    ```

    Make sure you're using port 222 (not 22) as specified in the Docker command.
  </Accordion>

  <Accordion title="Lost administrator password">
    **Reset via command line:**

    ```bash theme={null}
    docker exec -it gitea gitea admin user change-password \
      --username admin \
      --password new-password
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Configuration Guide" icon="gear" href="/admin/configuration">
    Learn about advanced configuration options and customization
  </Card>

  <Card title="Features Overview" icon="book" href="/features/repositories">
    Discover all features available in Gitea
  </Card>

  <Card title="API Documentation" icon="code" href="/api/overview">
    Integrate Gitea with other tools using the REST API
  </Card>

  <Card title="Actions & CI/CD" icon="rocket" href="/features/actions">
    Set up continuous integration and deployment pipelines
  </Card>
</CardGroup>

## Additional Resources

<CardGroup cols={2}>
  <Card title="Official Documentation" icon="book-open" href="https://docs.gitea.com">
    Comprehensive documentation for all Gitea features
  </Card>

  <Card title="Community Forum" icon="comments" href="https://forum.gitea.com">
    Get help and discuss with the community
  </Card>

  <Card title="Discord Server" icon="discord" href="https://discord.gg/Gitea">
    Chat with other Gitea users and developers
  </Card>

  <Card title="GitHub Repository" icon="github" href="https://github.com/go-gitea/gitea">
    Source code, issues, and contributions
  </Card>
</CardGroup>

<Note>
  **Congratulations!** You've successfully set up Gitea and created your first repository. You're now ready to use Gitea for your development projects!
</Note>