Skip to content

Commit 031fd49

Browse files
BeckettFreyBeckettFrey
authored
docs: Add Ubuntu Setup Instructions (#309) (#338)
* chore: auto fix pre-commit formatting issues (trailing whitespace, yaml, EOF) * feat: Clean slate startup script for ubuntu * feat: Enhance linux sys pkg script * docs: Ubuntu setup * revert: undo unintended formatting changes * docs: update script and docs for x86 compatibility * docs: enhance script * chore: address comments * chore: split script and update docs
1 parent 971dcbf commit 031fd49

File tree

7 files changed

+304
-0
lines changed

7 files changed

+304
-0
lines changed

‎CONTRIBUTING.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,36 @@ Beginner focused information can be found below in [Open a Pull Request](#openin
6464

6565
1. **Set Up Development Environment**:
6666

67+
- **System Dependencies (Linux)**: For Ubuntu 22.04+ or Debian-based systems (both x86 and ARM64 architectures), install required packages:
68+
69+
**Note:** Python 3.9+ is required for pre-commit hooks compatibility.
70+
71+
```sh
72+
# Install required packages directly
73+
sudo apt update
74+
sudo apt install -y \
75+
build-essential \
76+
curl \
77+
git \
78+
pkg-config \
79+
libssl-dev \
80+
libffi-dev \
81+
libyaml-dev \
82+
python3 \
83+
python3-venv \
84+
python3-pip
85+
```
86+
87+
Or use the provided system package script (automatically ensures Python 3.9+ compatibility):
88+
89+
```sh
90+
chmod +x ./scripts/linux/sys_pkgs_core.sh
91+
chmod +x ./scripts/linux/sys_pkgs_dev.sh
92+
# Installs required packages and ensures compatible Python version
93+
./scripts/linux/sys_pkgs_core.sh # For runtime dependencies only
94+
./scripts/linux/sys_pkgs_dev.sh # For Python/dev dependencies (calls core script)
95+
```
96+
6797
- Install dependencies:
6898

6999
```sh

‎README.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -150,6 +150,38 @@ openzeppelin-monitor/
150150

151151
### Development Environment Setup
152152

153+
#### Linux
154+
155+
To get started on Ubuntu 22.04+ or Debian-based systems (both x86 and ARM64 architectures):
156+
157+
**Note:** Python 3.9+ is required for pre-commit hooks compatibility.
158+
159+
```bash
160+
# Install required packages directly
161+
sudo apt update
162+
sudo apt install -y \
163+
build-essential \
164+
curl \
165+
git \
166+
pkg-config \
167+
libssl-dev \
168+
libffi-dev \
169+
libyaml-dev \
170+
python3 \
171+
python3-venv \
172+
python3-pip
173+
```
174+
175+
or run the linux system package script (automatically ensures Python 3.9+ compatibility):
176+
177+
```bash
178+
chmod +x ./scripts/linux/sys_pkgs_core.sh
179+
chmod +x ./scripts/linux/sys_pkgs_dev.sh
180+
# Installs required packages and ensures compatible Python version
181+
./scripts/linux/sys_pkgs_core.sh # For runtime dependencies only
182+
./scripts/linux/sys_pkgs_dev.sh # For Python/dev dependencies (calls core script)
183+
```
184+
153185
#### Prerequisites
154186

155187
- **Rust 2021 edition**, version `1.86` or later.

‎docs/modules/ROOT/pages/contribution.adoc‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,40 @@ Before contributing, ensure you have:
4040
* **Git** - For version control
4141
* **Python/pip** - For pre-commit hooks
4242

43+
=== System Dependencies (Linux)
44+
45+
For Ubuntu 22.04+ or Debian-based systems (both x86 and ARM64 architectures), install required packages:
46+
47+
**Note:** Python 3.9+ is required for pre-commit hooks compatibility.
48+
49+
[source,bash]
50+
----
51+
# Install required packages directly
52+
sudo apt update
53+
sudo apt install -y \
54+
build-essential \
55+
curl \
56+
git \
57+
pkg-config \
58+
libssl-dev \
59+
libffi-dev \
60+
libyaml-dev \
61+
python3 \
62+
python3-venv \
63+
python3-pip
64+
----
65+
66+
Or use the provided system package script (automatically ensures Python 3.9+ compatibility):
67+
68+
[source,bash]
69+
----
70+
chmod +x ./scripts/linux/sys_pkgs_core.sh
71+
chmod +x ./scripts/linux/sys_pkgs_dev.sh
72+
# Installs required packages and ensures compatible Python version
73+
./scripts/linux/sys_pkgs_core.sh // For runtime dependencies only
74+
./scripts/linux/sys_pkgs_dev.sh // For Python/dev dependencies (calls core script)
75+
----
76+
4377
=== Initial Setup
4478

4579
[source,bash]

‎docs/modules/ROOT/pages/index.adoc‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,40 @@ To get started immediately, see xref:quickstart.adoc[Quickstart].
4242
* Use **Rust 2021 edition**, version `1.86` or later.
4343
* **Docker** (optional, for containerized deployment)
4444

45+
==== System Dependencies (Linux)
46+
47+
For Ubuntu 22.04+ or Debian-based systems (both x86 and ARM64 architectures), install required packages:
48+
49+
**Note:** Python 3.9+ is required for pre-commit hooks compatibility.
50+
51+
[source,bash]
52+
----
53+
# Install required packages directly
54+
sudo apt update
55+
sudo apt install -y \
56+
build-essential \
57+
curl \
58+
git \
59+
pkg-config \
60+
libssl-dev \
61+
libffi-dev \
62+
libyaml-dev \
63+
python3 \
64+
python3-venv \
65+
python3-pip
66+
----
67+
68+
Or use the provided system package script (automatically ensures Python 3.9+ compatibility):
69+
70+
[source,bash]
71+
----
72+
chmod +x ./scripts/linux/sys_pkgs_core.sh
73+
chmod +x ./scripts/linux/sys_pkgs_dev.sh
74+
# Installs required packages and ensures compatible Python version
75+
./scripts/linux/sys_pkgs_core.sh // For runtime dependencies only
76+
./scripts/linux/sys_pkgs_dev.sh // For Python/dev dependencies (calls core script)
77+
----
78+
4579
=== Local Installation
4680

4781
. **Clone the repository:**

‎docs/modules/ROOT/pages/quickstart.adoc‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,34 @@ Before you begin, ensure you have the following installed:
2424
If you don't have Rust installed, visit https://rustup.rs/ to install it.
2525
====
2626

27+
=== System Dependencies (Linux)
28+
29+
For Ubuntu 22.04+ or Debian-based systems (both x86 and ARM64 architectures), install required packages:
30+
31+
**Note:** Python 3.9+ is required for pre-commit hooks compatibility.
32+
33+
[source,bash]
34+
----
35+
# Install required packages directly
36+
sudo apt update
37+
sudo apt install -y \
38+
build-essential \
39+
curl \
40+
git \
41+
pkg-config \
42+
libssl-dev \
43+
libffi-dev \
44+
libyaml-dev \
45+
----
46+
47+
Or use the provided system packages script:
48+
49+
[source,bash]
50+
----
51+
chmod +x ./scripts/linux/sys_pkgs_core.sh
52+
./scripts/linux/sys_pkgs_core.sh // For runtime dependencies only
53+
----
54+
2755
== Quick Setup Options
2856

2957
We provide two setup paths to get you started:

‎scripts/linux/sys_pkgs_core.sh‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
#!/bin/bash
2+
3+
set -euo pipefail
4+
5+
# Colors for pretty printing
6+
RED='\033[0;31m'
7+
GREEN='\033[0;32m'
8+
YELLOW='\033[1;33m'
9+
BLUE='\033[0;34m'
10+
CYAN='\033[0;36m'
11+
NC='\033[0m' # No Color
12+
13+
info() { echo -e "${BLUE}ℹ${NC} $*"; }
14+
success() { echo -e "${GREEN}✅${NC} $*"; }
15+
warn() { echo -e "${YELLOW}⚠${NC} $*"; }
16+
error() { echo -e "${RED}❌${NC} $*"; }
17+
step() { echo -e "${CYAN}➤${NC} $*"; }
18+
19+
# Don't run as root
20+
if [[ $EUID -eq 0 ]]; then
21+
error "Don't run this as root - it will use sudo when needed"
22+
exit 1
23+
fi
24+
25+
# Check if we're on Ubuntu/Debian
26+
if ! command -v apt-get >/dev/null; then
27+
error "This script requires apt-get (Ubuntu/Debian)"
28+
exit 1
29+
fi
30+
31+
step "Removing problematic cdrom sources..."
32+
sudo sed -i '/cdrom:/d' /etc/apt/sources.list /etc/apt/sources.list.d/*.list 2>/dev/null || true
33+
success "Cleaned up package sources"
34+
35+
# Update with retry
36+
step "Updating package lists..."
37+
for i in {1..3}; do
38+
if sudo apt-get update >/dev/null 2>&1; then
39+
success "Package lists updated"
40+
break
41+
elif [[ $i -eq 3 ]]; then
42+
error "Failed to update after 3 attempts"
43+
exit 1
44+
else
45+
warn "Retry $i failed, trying again in 5 seconds..."
46+
sleep 5
47+
fi
48+
49+
done
50+
51+
# Install core packages
52+
step "Installing core packages..."
53+
sudo apt-get install -y \
54+
build-essential \
55+
curl \
56+
git \
57+
pkg-config \
58+
libssl-dev \
59+
libffi-dev \
60+
libyaml-dev \
61+
software-properties-common \
62+
ca-certificates >/dev/null 2>&1
63+
success "Core packages installed"
64+
65+
echo -e "\n${GREEN}🎉 Core system setup complete!${NC}"

‎scripts/linux/sys_pkgs_dev.sh‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
#!/bin/bash
2+
3+
set -euo pipefail
4+
5+
# Colors for pretty printing
6+
RED='\033[0;31m'
7+
GREEN='\033[0;32m'
8+
YELLOW='\033[1;33m'
9+
BLUE='\033[0;34m'
10+
CYAN='\033[0;36m'
11+
NC='\033[0m' # No Color
12+
13+
info() { echo -e "${BLUE}ℹ${NC} $*"; }
14+
success() { echo -e "${GREEN}✅${NC} $*"; }
15+
warn() { echo -e "${YELLOW}⚠${NC} $*"; }
16+
error() { echo -e "${RED}❌${NC} $*"; }
17+
step() { echo -e "${CYAN}➤${NC} $*"; }
18+
19+
# Don't run as root
20+
if [[ $EUID -eq 0 ]]; then
21+
error "Don't run this as root - it will use sudo when needed"
22+
exit 1
23+
fi
24+
25+
# Check if we're on Ubuntu/Debian
26+
if ! command -v apt-get >/dev/null; then
27+
error "This script requires apt-get (Ubuntu/Debian)"
28+
exit 1
29+
fi
30+
31+
# Run core setup first
32+
step "Running core system setup..."
33+
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
34+
bash "$SCRIPT_DIR/sys_pkgs_core.sh"
35+
36+
# Install Python and dev tools
37+
step "Installing Python and dev tools..."
38+
sudo apt-get install -y \
39+
python3 \
40+
python3-venv \
41+
python3-pip >/dev/null 2>&1
42+
success "Python base packages installed"
43+
44+
# Check Python version
45+
step "Checking Python compatibility..."
46+
python_version=$(python3 -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")' 2>/dev/null || echo "unknown")
47+
info "Found Python $python_version"
48+
49+
python_ok=true
50+
if ! python3 -c "import sys; exit(0 if sys.version_info >= (3, 9) else 1)" 2>/dev/null; then
51+
python_ok=false
52+
fi
53+
54+
# Install newer Python if needed
55+
if [[ "$python_ok" == false ]]; then
56+
warn "Python $python_version is below recommended 3.9+"
57+
step "Installing Python 3.11 for better compatibility..."
58+
echo -e "${YELLOW}⚠ Adding deadsnakes PPA (third-party) for newer Python...${NC}"
59+
if ! find /etc/apt/sources.list.d -name "*deadsnakes*" | grep -q . 2>/dev/null; then
60+
info "Adding deadsnakes PPA..."
61+
sudo add-apt-repository -y ppa:deadsnakes/ppa >/dev/null 2>&1
62+
sudo apt-get update >/dev/null 2>&1
63+
else
64+
info "Deadsnakes PPA already configured"
65+
fi
66+
sudo apt-get install -y python3.11 python3.11-venv python3.11-dev >/dev/null 2>&1
67+
if ! python3.11 -m pip --version >/dev/null 2>&1; then
68+
info "Installing pip for Python 3.11..."
69+
sudo apt-get install -y python3.11-distutils >/dev/null 2>&1
70+
curl -fsSL https://bootstrap.pypa.io/get-pip.py | sudo python3.11 >/dev/null 2>&1
71+
fi
72+
success "Python 3.11 installed. Use: python3.11"
73+
else
74+
success "Python $python_version is compatible"
75+
fi
76+
77+
echo -e "\n${GREEN}🎉 Dev environment setup complete!${NC}"
78+
echo -e "${CYAN}Next steps:${NC}"
79+
echo -e " • Run ${YELLOW}python3 --version${NC} (or ${YELLOW}python3.11 --version${NC}) to verify"
80+
echo -e " • Install additional tools as needed"
81+
echo -e " • Happy coding!"

0 commit comments

Comments
 (0)