Feat/redpanda/v1 rc

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "foc-localnet"
-version = "0.1.0"
+version = "1.0.0-rc.1"
 edition = "2021"
 
 [build-dependencies]
@@ -34,4 +34,5 @@ flate2 = "1.0"
 tar = "0.4"
 reqwest = { version = "0.11", features = ["blocking"] }
 tracing = "0.1"
-tracing-subscriber = { version = "0.3", features = ["env-filter", "fmt"] }
+tracing-subscriber = { version = "0.3", features = ["env-filter", "fmt"] }
+sha2 = "0.10"

README.md

@@ -48,17 +48,17 @@ This will:
 ### Step 3: Start the Network
 
 ```bash
-cargo run -- start
+cargo run -- start --parallel
 ```
 
 This will:
 - Create the genesis block
 - Start Lotus daemon with FEVM enabled
 - Deploy FOC smart contracts (including MockUSDFC)
 - Start storage provider(s)
-- Launch Portainer UI for container management
+- Launch [Portainer UI](https://docs.docksal.io/use-cases/portainer/) for container management
 
-**If you are feeling adventurous**: Use `cargo run -- start --parallel`, an experimental feature that attempts to parallelize setup steps as much as possible. 
+**If you are have troubles**: Use `cargo run -- start`, removing parallelism during start, this may take longer.
 
 **That's it!** Your local Filecoin network is running.
 
@@ -88,7 +88,7 @@ Each can be:
 ### 🔒 Deterministic Setup
 - **Pinned versions**: All components use specific git tags/commits for reproducibility
 - **Deterministic keys**: Uses fixed seeds, generating the same keys on every setup
-- **Consistent addresses**: Find derived accounts in `~/.foc-localnet/state/addresses.json`
+- **Consistent state**: Each run preserves its context in `~/.foc-localnet/run/<run-id>/step_context.json`
 
 ### 🤖 Fully Automated
 From building Docker images to deploying contracts—everything is automated:
@@ -105,8 +105,9 @@ Built with modular steps for easy extension and customization:
 
 ### 📜 Programmable
 Built for scripting and automation:
-- **Contract addresses**: `~/.foc-localnet/state/contract_addresses.json`
-- **Account addresses**: `~/.foc-localnet/state/addresses.json`
+- **Contract addresses**: `~/.foc-localnet/run/<run-id>/contract_addresses.json`
+- **Step context**: `~/.foc-localnet/run/<run-id>/step_context.json`
+- **Latest run symlink**: `~/.foc-localnet/state/latest/` → points to most recent run
 - Write scripts for testing, demos, CI/CD pipelines, etc.
 
 ### 🌐 Isolated Networks
@@ -133,34 +134,21 @@ Bundled with Portainer for browser-based Docker management—no terminal wizardr
 
 ---
 
-## 📂 Where's My Data?
-
-Everything lives in `~/.foc-localnet/`:
-
-```
-~/.foc-localnet/
-├── state/
-│   ├── addresses.json           # Derived account addresses
-│   └── contract_addresses.json  # Deployed smart contracts
-├── artifacts/
-│   └── docker/volumes/          # Persistent container data
-├── logs/                        # Container logs
-├── repos/                       # Cloned Git repositories
-└── config.toml                  # Configuration
-```
-
----
-
 ## 🛠️ Need More?
 
-For advanced topics like:
-- Custom repository configurations
-- Multiple storage provider setups
-- Architecture deep-dives
-- Troubleshooting guides
-- API access and scripting
-
-See **[README_ADVANCED.md](README_ADVANCED.md)** for detailed documentation (coming soon).
+See **[Advanced_Readme.md](Advanced_Readme.md)** for comprehensive documentation on:
+- **All commands reference** (init, build, start, stop, status, version)
+- **Configuration system** (config.toml structure, parameters, editing)
+- **Complete directory structure** (what's stored where and why)
+- **Resetting and cleanup** (manual cleanup, disk management)
+- **Run ID and Step Context** (isolation mechanism, state sharing)
+- **Docker and networking** (container architecture, network topology, Portainer debugging)
+- **Repository management** (using local repos, sharing configurations)
+- **Command flags** (detailed explanations of all flags and when to use them)
+- **Lifecycle overview** (full startup sequence, step implementation)
+- **Service Provider examples** (1 SP with 0 authorized, 3 SPs with top 2 authorized, etc.)
+- **Troubleshooting guides** (port conflicts, build failures, network issues)
+- **Advanced topics** (custom genesis, Lotus API access, contract interaction)
 
 ---
 

build.rs

@@ -80,6 +80,15 @@ fn generate_mockusdfc_archive() {
         return;
     }
 
+    // Ensure artifacts directory exists
+    let artifacts_dir = Path::new("artifacts");
+    if !artifacts_dir.exists() {
+        if let Err(e) = std::fs::create_dir_all(artifacts_dir) {
+            eprintln!("Warning: Failed to create artifacts directory: {}", e);
+            return;
+        }
+    }
+
     // Create tar.gz archive in contracts/ directory
     let output = Command::new("tar")
         .args(["-czf", "artifacts/MockUSDFC.tar.gz", "contracts/MockUSDFC"])

docker/builder/Dockerfile

@@ -25,10 +25,11 @@ ENV PATH=$PATH:/usr/local/go/bin
 # Create foc-user and foc-group with matching host UID/GID when it is run. The 1002 below is just a placeholder which will be replaced during build process. See `docker.rs`
 ARG USER_ID=1002
 ARG GROUP_ID=1002
+RUN userdel ubuntu || true
 RUN groupadd -g ${GROUP_ID} foc-group && \
     useradd -l -u ${USER_ID} -g foc-group -m -s /bin/bash foc-user && \
     mkdir -p /home/foc-user/go/pkg && \
-    chown -R foc-user:foc-group /home/foc-user/go
+    chown -R foc-user:foc-group /home/foc-user
 
 # Install Rust as foc-user
 USER foc-user

docker/curio/Dockerfile

@@ -19,6 +19,7 @@ RUN apt-get update && apt-get install -y \
 # Create foc-user and foc-group with matching host UID/GID when it is run. The 1002 below is just a placeholder which will be replaced during build process. See `docker.rs`
 ARG USER_ID=1002
 ARG GROUP_ID=1002
+RUN userdel ubuntu || true
 RUN groupadd -g ${GROUP_ID} foc-group && \
     useradd -l -u ${USER_ID} -g foc-group -m -s /bin/bash foc-user
 

docker/lotus-miner/Dockerfile

@@ -18,6 +18,7 @@ RUN apt-get update && apt-get install -y \
 # Create foc-user and foc-group with matching host UID/GID when it is run. The 1002 below is just a placeholder which will be replaced during build process. See `docker.rs`
 ARG USER_ID=1002
 ARG GROUP_ID=1002
+RUN userdel ubuntu || true
 RUN groupadd -g ${GROUP_ID} foc-group && \
     useradd -l -u ${USER_ID} -g foc-group -m -s /bin/bash foc-user
 

docker/lotus/Dockerfile

@@ -20,6 +20,7 @@ RUN apt-get update && apt-get install -y \
 # Create foc-user and foc-group with matching host UID/GID when it is run. The 1002 below is just a placeholder which will be replaced during build process. See `docker.rs`
 ARG USER_ID=1002
 ARG GROUP_ID=1002
+RUN userdel ubuntu || true
 RUN groupadd -g ${GROUP_ID} foc-group && \
     useradd -l -u ${USER_ID} -g foc-group -m -s /bin/bash foc-user
 

docker/yugabyte/Dockerfile

@@ -17,6 +17,7 @@ ENV LC_ALL=en_US.UTF-8
 # Create foc-user and foc-group with matching host UID/GID when it is run. The 1002 below is just a placeholder which will be replaced during build process. See `docker.rs`
 ARG USER_ID=1002
 ARG GROUP_ID=1002
+RUN userdel ubuntu || true
 RUN groupadd -g ${GROUP_ID} foc-group && \
     useradd -l -u ${USER_ID} -g foc-group -m -s /bin/bash foc-user
 

src/cli.rs

@@ -59,6 +59,9 @@ pub enum Commands {
         /// Use random mnemonic instead of deterministic one
         #[arg(long)]
         rand: bool,
+        /// Skip building Docker images (useful when images are already cached)
+        #[arg(long)]
+        no_docker_build: bool,
     },
     /// Build Filecoin projects in a container
     Build {

src/commands/build/docker.rs

@@ -16,7 +16,7 @@ use super::Project;
 
 /// Build the builder Docker image.
 pub fn build_builder_image(dockerfile_dir: &str) -> Result<String, Box<dyn std::error::Error>> {
-    let image_tag = "foc-localnet-builder:latest";
+    let image_tag = "foc-builder";
 
     // Check if image already exists in Docker
     if image_exists(image_tag)? {
@@ -89,6 +89,8 @@ pub fn setup_docker_run_args(
         "foc-user".to_string(),
         "--name".to_string(),
         container_name,
+        "-e".to_string(),
+        "HOME=/home/foc-user".to_string(),
         "-v".to_string(),
         format!("{}:{}", source_dir, container_source_dir),
         "-v".to_string(),

src/commands/build/execution.rs → src/commands/build/exec.rs

@@ -10,7 +10,8 @@ use std::fs::OpenOptions;
 use std::io::{BufRead, BufReader, Write};
 use std::path::Path;
 use std::process::{Command, Stdio};
-use tracing::{error, info};
+use tracing::info;
+use tracing::warn;
 
 /// Run the build process inside the Docker container.
 pub fn run_build_in_container(
@@ -67,34 +68,35 @@ pub fn execute_build_process(
     let stdout = child.stdout.take().ok_or("Failed to capture stdout")?;
     let stderr = child.stderr.take().ok_or("Failed to capture stderr")?;
 
-    // Create clones of the log file for writing
-    let log_file_clone = OpenOptions::new()
+    // Create log file
+    let log_file = OpenOptions::new()
         .create(true)
         .append(true)
         .open(log_path)?;
 
+    info!("NOTE: StdErr output does not necessarily indicate failure");
+
+    std::thread::sleep(std::time::Duration::from_secs(5));
+
     // Stream stdout to both console and log file
     let stdout_handle = std::thread::spawn({
-        let mut log_file = log_file_clone;
+        let mut log_file = log_file.try_clone()?;
         move || {
             let reader = BufReader::new(stdout);
             for line in reader.lines().flatten() {
-                info!("{}", line);
+                info!("(stdout): {}", line);
                 writeln!(log_file, "{}", line).ok();
             }
         }
     });
 
     // Stream stderr to both console and log file
     let stderr_handle = std::thread::spawn({
-        let mut log_file = OpenOptions::new()
-            .create(true)
-            .append(true)
-            .open(log_path)?;
+        let mut log_file = log_file.try_clone()?;
         move || {
             let reader = BufReader::new(stderr);
             for line in reader.lines().flatten() {
-                error!("{}", line);
+                warn!("(stderr): {}", line);
                 writeln!(log_file, "{}", line).ok();
             }
         }

src/commands/build/mod.rs

@@ -3,7 +3,7 @@
 //! This module handles building Filecoin projects (Lotus and Curio) in a Docker container.
 
 pub mod docker;
-pub mod execution;
+pub mod exec;
 pub mod logging;
 pub mod repository;
 
@@ -14,7 +14,7 @@ use std::fs;
 use tracing::info;
 
 use self::docker::build_builder_image;
-use self::execution::run_build_in_container;
+use self::exec::run_build_in_container;
 
 /// Build a project in a Docker container.
 ///

src/commands/init/mod.rs

@@ -94,6 +94,7 @@ fn cleanup_previous_installation() -> Result<(), Box<dyn std::error::Error>> {
 /// * `proof_params_dir` - Optional path to local filecoin-proof-params directory
 /// * `force` - Whether to force regeneration of config file
 /// * `use_random_mnemonic` - Whether to use random mnemonic for key generation
+/// * `no_docker_build` - Whether to skip artifact downloads and Docker image builds (use when images are already cached)
 ///
 /// # Returns
 /// Returns `Ok(())` on successful initialization, or an error if any step fails.
@@ -107,6 +108,7 @@ pub fn init_environment(
     proof_params_dir: Option<String>,
     force: bool,
     use_random_mnemonic: bool,
+    no_docker_build: bool,
 ) -> Result<(), Box<dyn std::error::Error>> {
     info!("Initializing foc-localnet environment...");
 
@@ -135,11 +137,16 @@ pub fn init_environment(
     // Download code repositories
     repositories::download_code_repositories()?;
 
-    // Download required artifacts (or copy from local paths)
-    artifacts::download_artifacts(yugabyte_archive, proof_params_dir)?;
+    // Download required artifacts and build Docker images (unless skipped)
+    if no_docker_build {
+        info!("Skipping artifact downloads and Docker image builds (--no-docker-build flag set)");
+    } else {
+        // Download required artifacts (or copy from local paths)
+        artifacts::download_artifacts(yugabyte_archive, proof_params_dir)?;
 
-    // Build and cache Docker images
-    crate::docker::build::build_and_cache_docker_images()?;
+        // Build and cache Docker images
+        crate::docker::build::build_and_cache_docker_images()?;
+    }
 
     info!("✓ Initialization completed successfully");
     info!("You can now start the localnet with 'foc-localnet start'");

src/commands/requirements/mod.rs

@@ -95,25 +95,16 @@ fn install_docker() -> Result<(), Box<dyn std::error::Error>> {
         if setup_docker::linux::is_ubuntu_or_debian()? {
             setup_docker::linux::install_docker_ubuntu()?;
         } else {
-            eprintln!(
-                "{}",
-                "❌ Automatic Docker installation is only supported on Ubuntu/Debian Linux."
-            );
+            eprintln!("❌ Automatic Docker installation is only supported on Ubuntu/Debian Linux.");
             return Err("Unsupported Linux distribution".into());
         }
     } else if cfg!(target_os = "macos") {
         // On macOS, Docker installation is handled by Homebrew
-        eprintln!("{}", "❌ Please install Docker Desktop manually on macOS.");
-        eprintln!(
-            "{}",
-            "Download from: https://www.docker.com/products/docker-desktop"
-        );
+        eprintln!("❌ Please install Docker Desktop manually on macOS.");
+        eprintln!("Download from: https://www.docker.com/products/docker-desktop");
         return Err("Manual Docker installation required on macOS".into());
     } else {
-        eprintln!(
-            "{}",
-            "❌ Automatic Docker installation is not supported on this platform."
-        );
+        eprintln!("❌ Automatic Docker installation is not supported on this platform.");
         return Err("Unsupported platform".into());
     }