DEV Community: Allwell

How To Make A Custom Type Iterable In Rust.

Allwell — Tue, 11 Nov 2025 20:45:01 +0000

Learn how to make your custom type implement the IntoIterator, Iterator, and FromIterator trait. Understand how to add the into_iter, iter, and iter_mut methods to your custom type.

In my former article, How to build a Heapless Vector using MaybeUninit<T> for Better Performance, I taught how to build a heapless vector data structure to enable a Vec-like data structure without heap allocation for use in embedded systems where heap allocation is unlikely. The heapless vector ArrayVec is a wrapper type over a fixed-sized array that utilizes uninitialized, stack, and static memory to mimic the functionality of a variably-sized Vec<T> with methods like try_push(), get(), and as_slice() to convert the type into a slice with pointer references to its array values.

In this article, we'll learn how to iterate through ArrayVec. As a custom type, we will implement iterator traits on ArrayVec that make it iterable (e.g. usable in a for loop).

These are the traits we'll learn about and implement:

IntoIterator
Iterator
FromIterator
Extend

Let's describe what these traits mean and do in Rust and why they're important in making a type iterable.

Iterator Traits

`IntoIterator`

The IntoIterator trait is the foundation for making your custom type (in our case, ArrayVec) iterable in for loops (e.g., for item in &vec { ... }) and compatible with iterator methods like map, filter, etc. It defines how to convert your type into an iterator, with an associated Item type (such as T for by-value, &T for by-reference, or &mut T for by-mutable-reference) and IntoIter type (the actual iterator type of your custom type, also known as concrete iterator).

Let's elaborate a little further on the meaning of the IntoIterator::IntoIter associated type and the concrete iterator it points to: To make ArrayVec iterable, we implement IntoIterator on ArrayVec and set the IntoIter associated type to something like ArrayVecIntoIter. Why? Because when we call into_iter() on ArrayVec it returns, ArrayVecIntoIter, an iterator (i.e. a type that implements the Iterator trait). How do we make ArrayVecIntoIter an iterator? By creating a new type, ArrayVecIntoIter, that mirrors iterable and utility fields on ArrayVec and implements Iterator. So we make ArrayVecIntoIter an iterator by implementing the required next method on it, along with other provided methods if we need them. That way, when you call into_iter() on ArrayVec and get ArrayVecIntoIter, you can continuously call next() on ArrayVecIntoIter to iterate through the values in ArrayVec. That, in a nutshell, is how you make ArrayVec iterable using IntoIterator.

Before putting all this into practice, below is the code that implements ArrayVec and it's functionality (as built in the previous article). After going through the code and understanding it, we'll start making ArrayVec iterable.

#![no_std]
extern crate std;
use arrayvec::ArrayVec;

mod arrayvec {
    use core::mem::MaybeUninit;

    #[derive(Debug)]
    pub struct ArrayVec<T, const N: usize> {
        values: [MaybeUninit<T>; N],
        len: usize,
    }

    impl<T, const N: usize> ArrayVec<T, N> {
        /// Creates a new empty ArrayVec with an array of uninitialized `T`
        /// and `len` = 0.
        pub fn new() -> Self {
            ArrayVec {
                // values: unsafe { MaybeUninit::uninit().assume_init() },
                // Below is same as the commented code above but safer.
                values: [const { MaybeUninit::uninit() }; N],
                len: 0,
            }
        }

        /// Pushes `T` if all `N` elements have not been initialized;
        /// else returns `Err(T)`.
        pub fn try_push(&mut self, value: T) -> Result<(), T> {
            if self.len == N {
                return Err(value);
            }
            self.values[self.len].write(value);
            self.len += 1;
            Ok(())
        }

        /// Returns a reference to the element at `index` if within bounds
        /// and initialized; else returns `None`.
        ///
        /// SAFETY: Unsafe internally: Assumes the first `len` slots are
        /// initialized.
        pub fn get(&self, index: usize) -> Option<&T> {
            if index >= self.len {
                return None;
            }
            unsafe { Some(&*self.values[index].as_ptr()) }
        }

        /// Pops the last value, if any, returning owned `T` (or `None`
        /// if empty).
        ///
        /// SAFETY: Uses `.assume_init_read()` to extract (read) and mark
        /// memory as uninitialized (this is also helped by the
        /// decrementing of `self.len` for the next `try_push`).
        pub fn pop(&mut self) -> Option<T> {
            if self.len == 0 {
                return None;
            }
            self.len -= 1;
            Some(unsafe { self.values[self.len].assume_init_read() })
        }

        /// Getter for current length.
        pub fn len(&self) -> usize {
            self.len
        }

        /// Return a slice using `slice::from_raw_parts()`. Returns a slice
        /// over initialized elements (i.e. first `self.len` slots).
        ///
        /// SAFETY: Unsafe internally, but safe API: assumes invariant holds.
        /// Length points to valid length of init elements.
        pub fn as_slice(&self) -> &[T] {
            unsafe {
                core::slice::from_raw_parts(
                    self.values.as_ptr() as *const T, self.len
                )
            }
        }

        /// Returns a mutable slice over initialized elements.
        ///
        /// SAFETY: Length param is valid length of init elements.
        pub fn as_mut_slice(&mut self) -> &mut [T] {
            unsafe {
                core::slice::from_raw_parts_mut(
                    self.values.as_mut_ptr() as *mut T, self.len
                )
            }
        }
    }

    // Implement Drop for ArrayVec to safely deallocate initialized elements.
    impl<T, const N: usize> Drop for ArrayVec<T, N> {
        fn drop(&mut self) {
            /* SAFETY: Explicitly drops the first `len` initialized elements.
            Therefore, no double frees. */
            for i in 0..self.len {
                unsafe {
                    self.values[i].assume_init_drop();
                }
            }
        }
    }
}

const CAP: usize = 5;

fn main() {
    {
        // A:
        let mut arr_vec = ArrayVec::<i32, CAP>::new();
        std::println!("{:?}", arr_vec); // View init ArrayVec

        let mut count;

        // Push a few elements
        for i in 0..(CAP - 2) {
            count = 1 + i as i32;
            arr_vec.try_push(count).unwrap()
        }
        std::println!("{:?}", arr_vec); // View pushed elements

        // Return elements in initialized index.
        let arr_els = arr_vec.as_slice();
        std::println!("---\nInit values: {:?}", arr_els);

        // Pop from MaybeUninit ArrayVec; if uninit, return None.
        std::println!("---\nArrayVec `len` before pop: {}", arr_vec.len());
        std::println!("Popped value: {:?}", arr_vec.pop());
        std::println!("ArrayVec `len` after pop: {}", arr_vec.len());

        // TEST: Add more elements beyond `CAP` size for ArrayVec;
        // `try_push` should escape and return with Err.
        let arr_len = arr_vec.len();
        count = *arr_vec.get(arr_len - 1).unwrap(); /* I can deref the pointer
        for the value here without moving the value because I know it's a
        primitive value which enables bitwise copy. */
        let mut arr_err_els: ArrayVec<Result<(), i32>, CAP> =
            ArrayVec::new();

        for _ in arr_len..(CAP * 2) {
            count += 1;
            if let Err(value) = arr_vec.try_push(count) {
                arr_err_els.try_push(Err(value)).unwrap();
            }
        }
        std::println!("---\nFilled ArrayVec: {:?}", arr_vec.as_slice());
        std::println!("Err beyond ArrayVec: {:?}", arr_err_els.as_slice());
    }
}

Figure 1: Complete former implementation of ArrayVec.

Having understood the implementation and functionality of ArrayVec, next we implement IntoIterator on ArrayVec.

Implementing `IntoIterator` for `ArrayVec`

ArrayVec has two methods, as_slice and as_mut_slice, that return a slice of the array. A cool thing about slice types is they implement methods, iter and iter_mut, that let you return an iterator over the slice elements; immutably & or mutably &mut referenced, respectively. Let's start by implementing iter and iter_mut methods on ArrayVec to return iterators from slices of ArrayVec.

// ...earlier code.

mod arrayvec {
    // ...earlier code.

    impl<T, const N: usize> ArrayVec<T, N> {
        // ...earlier code.

        /// Use slice iterator for immutable iteration of ArrayVec.
        pub fn iter(&self) -> core::slice::Iter<'_, T> {
            self.as_slice.iter()
        }

        /// Use slice iterator for mutable iteration of ArrayVec.
        pub fn iter_mut(&mut self) -> core::slice::IterMut<'_, T> {
            self.as_mut_slice.iter_mut()
        }
    }
}

Figure 2: Converting slices of ArrayVec into iterators.

With this implementation in place, when we call ArrayVec::iter or ArrayVec::iter_mut, we'll get a type that is Iterator and allows us iterate through elements of ArrayVec.

Three things must happen before we can successfully implement IntoIterator on ArrayVec:

Provide IntoIterator::IntoIter associated type for ArrayVec by creating ArrayVecIntoIter type.
Implement Iterator for ArrayVecIntoIter.
Implement Drop for ArrayVecIntoIter. You'll see why we do this later.

1. Create ArrayVecIntoIter Type.

// ...earlier code.

mod arrayvec {
    // ...earlier code.

    // Build out iterator type for ArrayVec as ArrayVecIntoIter<T, N>
    // Consuming iterator (by-value): Moves out owned T.
    // But will provide iterators for fundamental types: & and &mut
    #[derive(Debug)]
    pub struct ArrayVecIntoIter<T, const N: usize> {
        values: [MaybeUninit<T>; N],
        len: usize,
        index: usize,
    }
}

Figure 3: Creating ArrayVecIntoIter—ArrayVec's iterator.

Notice ArrayVecIntoIter is similar in structure to ArrayVec, only difference being the index field. This field would be used to track how many initialized elements in values: [MaybeUninit<T>; N] array have been iterated over.

2. Implement Iterator for ArrayVecIntoIter.

// ...earlier code.

mod arrayvec {
    // ...earlier code.

    // Implement Iterator trait on ArrayVecIntoIter making it an iterator.
    impl<T, const N: usize> Iterator for ArrayVecIntoIter<T, N> {
        type Item = T;

        fn next(&mut self) -> Option<Self::Item> {
            if self.index >= self.len {
                return None;
            }
            let i = self.index; 
            self.index += 1;
            // SAFETY: i < len, so slot is init
            Some(unsafe { self.values[i].assume_init_read() })
        }

        fn size_hint(&self) -> (usize, Option<usize>) {
            let remaining = self.len.saturating_sub(self.index);
            (remaining, Some(remaining))
        }
    }
}

Figure 4: Implementing Iterator for ArrayVecIntoIter.

Iterator::Item associated type for ArrayVecIntoIter<T, N> is T. We setup two methods, next and size_hint. next is a required Iterator method and we set it up to return Option<Self::Item> in other words Option<T> for ArrayVecIntoIter<T, N>.

In next, we check if the iterator index tracker (self.index) value equates to the vector initialized element tracker (self.len), if yes, we return None immediately because that means, we've reached the end of iteration. That way we create a safe API over unsafe code by not reading uninitialized values (which is undefined behaviour UB). .assume_init_read() reads the initialized values and returns them owned. This is why we get the return type of Option<Self::Item>. Self::Item, which is T, is an owned value.

Review the previous article to understand, in detail, what .assume_init_read() does as it dereferences and reads the value behind the MaybeUninit<T>.

size_hint as the name suggests is a method that computes and returns bounds on the remaining length of the iterator. It returns a tuple where the first element is the lower bound, and the second element is the upper bound. To learn more about size_hint, see the stdlib docs on Iterator methods. We use the value retrieved from this method later on (I'll call your attention back to this then).

With these two methods implemented, ArrayVecIntoIter is now an iterator for ArrayVec.

3. Implement Drop for ArrayVecIntoIter.

// ...earlier code.

mod arrayvec {
    // ...earlier code.

    // Implement Drop trait to safely deallocate initialized elements
    // from ArrayVecIntoIter<T, N> MaybeUninit<T> values
    impl<T, const N: usize> Drop for ArrayVecIntoIter<T, N> {
        fn drop(&mut self) {
            // Drop remaining init elements (from index to len)
            // SAFETY: Invariant holds for those slots.
            for i in self.index..self.len {
                unsafe {
                    self.values[i].assume_init_drop();
                }
            }
            // Uninit slots auto-drop as MaybeUninit: meaning as "garbage"
            // bytes they are overwritten by the next write.
        }
    }
}

Figure 5: Implementing Drop for ArrayVecIntoIter.

Next, we implement Drop for ArrayVecIntoIter to deallocate initialized elements that have yet to be iterated over, if any. Hence why in the for loop, we iterate over usize range of self.index..self.len. In a scenario where we've iterated through all initialized elements (self.index == self.len) then .assume_init_drop() will not be called (therefore no double-frees).

Why is it important though to implement Drop for ArrayVecIntoIter especially since we already implemented Drop for ArrayVec?

The reason is because when we convert ArrayVec into its iterator ArrayVecIntoIter, fields of ArrayVec will be moved in the <ArrayVec as IntoIterator>::into_iter method into similar fields in ArrayVecIntoIter. Therefore, we need to, as we did for ArrayVec, manually drop the uninitialized values now moved to ArrayVecIntoIter. More on this later.

Now, we can successfully implement IntoIterator on ArrayVec.

// ...earlier code.

mod arrayvec {
    // ...earlier code.

    // Finally, implement IntoIterator for ArrayVec; returns
    // an iterator (ArrayVecIntoIter).
    impl<T, const N: usize> IntoIterator for ArrayVec<T, N> {
        type Item = T;
        type IntoIter = ArrayVecIntoIter<T, N>;

        fn into_iter(self) -> Self::IntoIter {
            // Wrap `self` inside ManuallyDrop so ArrayVec Drop cannot
            // be called on ArrayVec. Prevents double-free.
            // Drop will be handled by ArrayVecIntoIter.
            let this = ManuallyDrop::new(self);
            // SAFETY: Read (bitwise copy) into `values` and `len`,
            // since `self` is consumed by function call; `this` will not
            // be used again.
            let values = unsafe { ptr::read(&this.values) };
            let len = unsafe { ptr::read(&this.len) };

            ArrayVecIntoIter {
                values,
                len,
                index: 0,
            }
        }
    }
}

Figure 6: Implementing IntoIterator for ArrayVec.

First observation is that into_iter consumes self and returns an iterator: Self::IntoIter (i.e. <ArrayVec as IntoIterator>::IntoIter) which points to ArrayVecIntoIter. This is precisely why we first needed to create the iterator, ArrayVecIntoIter, for ArrayVec.

As self is consumed, if we tried to perform a simpler operation by transferring ownership of self's values, the compiler would have panicked with an error. Below is an example.

// ...earlier code.

mod arrayvec {
    // ...earlier code.

    impl<T, const N: usize> IntoIterator for ArrayVec<T, N> {
        type Item = T;
        type IntoIter = ArrayVecIntoIter<T, N>;

        fn into_iter(self) -> Self::IntoIter {
            ArrayVecIntoIter {
                values: self.values,
                len: self.len,
                index: 0,
            }
        }
    }
}

Figure 7: Rewriting code in Figure 6 in a simpler operation.

Panics with error:

  Compiling playground v0.0.1 (/playground)
error[E0509]: cannot move out of type `arrayvec::ArrayVec<T, N>`, which implements the `Drop` trait
   --> src/main.rs:190:25
    |
190 |                 values: self.values,
    |                         ^^^^^^^^^^^
    |                         |
    |                         cannot move out of here
    |                         move occurs because `self.values` has type `[MaybeUninit<T>; N]`, which does not implement the `Copy` trait

For more information about this error, try `rustc --explain E0509`.
error: could not compile `playground` (bin "playground") due to 1 previous error

Figure 8: Compiler error panic from running code in Figure 7.

This error states that the compiler cannot move out of self because self (ArrayVec) implements Drop.

Remember, in the Drop implementation of ArrayVec, we iterated through a range that had self.len as the upper bound, and within the iteration we called .assume_init_drop() on the initialized elements of the self.values array. Accessing fields of ArrayVec in drop is the reason why the error code in Figure 8 occurs in a simple operation in Figure 7.

Because ArrayVec implements Drop and, in the implementation, accesses its fields, when we attempt to move out of self in <ArrayVec as IntoIterator>::into_iter the compiler panics saying, "Hey, self.values will be moved out here which means by the time I call drop on ArrayVec which is self when into_iter finishes running, in <ArrayVec as Drop>::drop I'll be accessing fields of self that have had their values moved therefore causing undefined behaviour UB. I cannot allow memory safety errors and UB therefore this is an error and you have to fix this code." Just imagine the compiler was a real person and had this conversation with you.

The way to fix that error is the reason for the implementation in Figure 7: by wrapping self (i.e. ArrayVec) in core::mem::ManuallyDrop<T>.

ManuallyDrop wraps ArrayVec to suppress its Drop impl during the transfer, then we unsafe-read fields, using core::ptr::read (similar in function to MaybeUninit::assume_init_read), into ArrayVecIntoIter (the iterator, which takes full ownership). Then we implement Drop for ArrayVecIntoIter to deallocate owned values. Finally, ArrayVecIntoIter's Drop and next handle dropping iterator consumed/unconsumed elements correctly—no leaks, no doubles.

A lot has been explained already but we've only just iterated over owned values of ArrayVec. We also need to be able to iterate over borrowed values. Usually known as fundamental types (& and &mut). Let's do that next.

Implementing `IntoIterator` for `&ArrayVec` and `&mut ArrayVec`

This is simpler than enabling iteration for owned values. Here, we simply call the iter and iter_mut methods on ArrayVec and return a slice iterator.

// ...earlier code.

mod arrayvec {
    // ...earlier code.

    // Implement IntoIterator for fundamental types of ArrayVec: & and &mut.
    // By reference: yields &T
    impl<'a, T, const N: usize> IntoIterator for &'a ArrayVec<T, N> {
        type Item = &'a T;
        type IntoIter = core::slice::Iter<'a, T>;

        fn into_iter(self) -> Self::IntoIter {
            self.as_slice().iter()
        }
    }

    // By mutable reference: yields &mut T
    impl<'a, T, const N: usize> IntoIterator for &'a mut ArrayVec<T, N> {
        type Item = &'a mut T;
        type IntoIter = core::slice::IterMut<'a, T>;

        fn into_iter(self) -> Self::IntoIter {
            self.as_mut_slice().iter_mut()
        }
    }
}

Figure 9: Implementing IntoIterator for fundamental types of ArrayVec.

As you can see, it's a much simpler implementation to that of owned values. In real-word use cases, iterating over borrowed values or values that exist in the buffer, in embedded contexts usually fulfills 80% of your needs. Since in embedded contexts, due to limited compute resources, consumption (or in Rust terms, moving) of values is discouraged while reusing the buffer is encouraged.

Testing

With the previous implementations, ArrayVec is now iterable in a for loop. Let's test it.

#![no_std]
extern crate std;
use arrayvec::ArrayVec;

mod arrayvec { /* ...`ArrayVec` implementation. */ }

const CAP: usize = 5;

fn main() {
    // { /* A: ...earlier code */ }
    {
        // B:
        // Iterating over ArrayVec through fundamental types: & and &mut

        // Shared iteration
        let mut arr_vec = ArrayVec::<u8, CAP>::new();
        let mut count;
        for i in 0..CAP {
            count = 1 + i as u8;
            arr_vec.try_push(count).unwrap(); // Init values on ArrayVec
        }
        std::println!("---");
        count = 0;
        for i in &arr_vec {
            std::println!("ArrayVec at index {}: {}", count, i);
            count += 1;
        }

        // Mutable iteration
        for value in &mut arr_vec {
            *value += 10;
        }
        std::println!("---\nMutated ArrayVec: {:?}", arr_vec.as_slice());
    }

    {
        // C:
        // Iterating over owned values of ArrayVec by calling `into_iter`
        let mut arr_vec = ArrayVec::<u8, CAP>::new();
        let mut count;
        for i in 0..(CAP - 1) {
            count = 1 + i as u8;
            arr_vec.try_push(count).unwrap();
        }
        let mut arr_iter = arr_vec.into_iter(); // move arr_vec
        // std::println!("{:?}", arr_vec); // should return move error
        /* Above code confirms `impl IntoIterator for ArrayVec` safety
        invariants.
        */
        std::println!("---\n{:?}", arr_iter); /* View created
        ArrayVecIntoIter. See `len` and `index` fields.
        */

        let mut arr_vec2 = ArrayVec::<Option<u8>, CAP>::new();
        loop { /* Loop through calls to `next()` to iterate through
        ArrayVecIntoInter.
        */
            match arr_iter.next() {
                Some(val) => arr_vec2.try_push(Some(val)).unwrap(),
                None => {
                    arr_vec2.try_push(None).unwrap();
                    break;
                }
            }
        }
        std::println!("{:?}", arr_iter); /* Review `len` and `index` fields.
        Notice index incr caused by calling `next()` on ArrayVecIntoIter.
        */
        std::println!("{:?}", arr_vec2.as_slice());
    }
}

Figure 10: Testing the iteration of ArrayVec in a for loop for fundamental types and owned values.

In Scope B, we test for iteration through fundamentals types. While in Scope C, we test for iteration over owned values.

After running the code in Figure 10 with cargo run, we get:

# ...earlier output.
---
ArrayVec at index 0: 1
ArrayVec at index 1: 2
ArrayVec at index 2: 3
ArrayVec at index 3: 4
ArrayVec at index 4: 5
---
Mutated ArrayVec: [11, 12, 13, 14, 15]
---
ArrayVecIntoIter { values: [MaybeUninit<u8>, MaybeUninit<u8>, MaybeUninit<u8>, MaybeUninit<u8>, MaybeUninit<u8>], len: 4, index: 0 }
ArrayVecIntoIter { values: [MaybeUninit<u8>, MaybeUninit<u8>, MaybeUninit<u8>, MaybeUninit<u8>, MaybeUninit<u8>], len: 4, index: 4 }
[Some(1), Some(2), Some(3), Some(4), None]

Figure 11: Terminal return from running code in Figure 10.

In Scope C, when we call into_iter() on arr_vec, arr_vec is moved yet there's no panic for a Drop on arr_vec because we wrapped arr_vec in a ManuallyDrop<T> in the <ArrayVec as IntoIterator>::into_iter method. Because the consumption of self, the invariants in into_iter are upheld because arr_vec can no longer be used after the move. This is one of the awesome characteristics of the Rust programming language. Its ability to enforce memory safety through types and the borrow checker.

Some other things you also see in play after the test like the index field of the ArrayVec iterator (ArrayVecIntoIter).

We've learned about IntoIterator and Iterator, and how to implement them. Next, we'll look at FromIterator and Extend.

`FromIterator`

The FromIterator trait, when implemented on your custom type, allows you to fill your custom collection type with output from another iterator. It does this by showing your custom collection type how to fill itself with outputs from another iterator, of course this is implemented in code.

A simple way to understand this is the collect method on T, where T: Iterator. The collect method collects outputs of an iterator into a collection type (like Vec<T>, etc.). The collect method actually uses the FromIterator trait behind the scenes by calling the FromIterator::from_iter method on the collection type it's collecting the iterator outputs into, thereby filling the type.

Seeing the code will help you understand it better.

// ...earlier code.

mod arrayvec {
    // ...earlier code.

    impl<T, const N: usize> FromIterator<T> for ArrayVec<T, N> {
        fn from_iter<I>(iter: I) -> Self
        where
            I: IntoIterator<Item = T>
        {
            let mut arr_vec = Self::new();
            let iter = iter.into_iter();

            // Optimize: If hinted size > N, take only N to skip
            // early access.
            let (lower, _) = iter.size_hint();
            if lower > N {
                for item in iter.take(N) {
                    let _ = arr_vec.try_push(item); /* Won't fail as
                    len < N.
                    */
                }
                return arr_vec;
            }

            // General case: Push until full (truncates excess).
            for item in iter {
                let _ = arr_vec.try_push(item); /* Err(item) dropped
                if full.
                */
            }
            arr_vec
        }
    }
}

Figure 12: Implementing FromIterator for ArrayVec.

The FromIterator implementation is a little more generic compared to the IntoIterator impl for ArrayVec. Here, FromIterator is generic over T which means the output of the iterator must be the same type as the elements inserted in the ArrayVec collection.

We see the use of the size_hint method as it's used to check the lower bound of the iterator (iter); if more than N, we take N capacity from it otherwise we simply iterate through iter, fill and return Self.

Testing

Testing FromIterator will be the shortest test because it's s straight forward, simpler process, but one that will help you understand how collect works under the hood.

#![no_std]
extern crate std;
use arrayvec::ArrayVec;

mod arrayvec { /* ...`ArrayVec` implementation. */ }

const CAP: usize = 5;

fn main() {
    // { /* A: ...earlier code */ }
    // { /* B: ...earlier code */ }
    // { /* C: ...earlier code */ }
    {
        // D:
        // Test FromIterator implementation with iterators on ArrayVec.

        // Using collect:
        let arr_vec = (-10..10).collect::<ArrayVec<i8, 15>>();
        std::println!("---\n{:?}", arr_vec.as_slice());

        // Using from_iter:
        let arr_vec = ArrayVec::<_, 5>::from_iter(-3..5 as i8); /* Using
        type inference for `T` in `ArrayVec<T, N>` helped by type cast
        on iterator.
        */
        std::println!("{:?}", arr_vec.as_slice());
    }
}

Figure 13: Testing FromIterator implementation on ArrayVec.

Returns:

# ...earlier code.
---
[-10, -9, -8, -7, -6, -5, -4, -3, -2, -1, 0, 1, 2, 3, 4]
[-3, -2, -1, 0, 1]

Figure 14: Terminal return from running code in Figure 13.

Notice in Figure 13 that from_iter can be used either indirectly through collect or directly as an associated function (i.e. <YourCustomType as FromIterator>::from_iter).

`Extend`

Extend is a shorter implementation compared to FromIterator that also benefits from IntoIterator. Extend is pretty intuitive for its use in that it enables you extend a collection with the contents of an iterator.

// ...earlier code.

mod arrayvec {
    // ...earlier code.

    impl<T, const N: usize> Extend<T> for ArrayVec<T, N> {
        fn extend<I: IntoIterator<Item = T>>(&mut self, iter: I) {
            for item in iter { // Stops iterating when `iter` is consumed
                if let Err(_) = self.try_push(item) { /* break if
                `self` is full
                */
                    break;
                }
            }
        }
    }
}

Figure 15: Implementing Extend for ArrayVec.

The Extend::extend method takes a mutable reference of self (&mut self) and a type that is iterable (iter), iterates through iter and pushes its items into self. Pretty straight forward right? Told you.

Before testing Extend, I want to add a functionality to ArrayVec that allows us to see which elements in the array are initialized, represented as Some(T), and which are uninitialized, represented as None. If you recognized it, you're right. It's similar to the function of the as_slice method in ArrayVec but slightly different in that it doesn't add uninitialized slots to the slice (as it shouldn't). With this new function, which I want to call show_init, we'll be able to see both initialized and uninitialized slots of the ArrayVec fixed-size array, as Some(T) and None respectively.

To understand why we're trying to see the initialized and uninitialized values of ArrayVec, see the previous article to learn more.

The only caveat of show_init is that it only works where T in ArrayVec<T, N> is copyable (T: Copy). This is the norm for primitive types but not more so for heap-alloc values. Fortunately for us, we're working in a no_std/embedded context where heap-alloc values are mostly prohibited. The reason for this constraint on show_init is because within its implementation, we dereference T to perform a bitwise copy of its value to another memory location. If T is not copyable (i.e. T: Clone), T will be moved, which is UB and foundational to use-after-free or double-free errors. We want to avoid that and enforce only copyable types in our code, therefore we add a trait bound in a where clause, T: Copy.

// ...earlier code.

mod arrayvec {
    // ...earlier code.

    // Implement these only where `T` is `Copy`.
    /* Better this way because in some impls we dereference `T`;
    if `T` is not `Copy` we'll be creating a use-after-free or
    double-free which is UB.
    */
    impl<T, const N: usize> ArrayVec<T, N>
    where
        T: Copy,
    {
        /// Returns Self with a view of initialized and uninitialized
        /// accesses of memory.
        pub fn show_init<'a>(&self, other: &'a mut ArrayVec<Option<T>, N>)
        -> &'a [Option<T>]
        {
            let mut count = 0;

            for item in self {
                let _ = other.try_push(Some(*item)); /* deref `T` to copy
                primitive value.
                */
                count += 1;
            }
            while count < N {
                let _ = other.try_push(None);
                count += 1;
            }
            other.as_slice()
        }
    }
}

Figure 16: Adding show_init method to ArrayVec for improved testing utility.

I won't go into the depth of explaining lifetimes in Rust and why show_init is generic for the lifetime 'a , but I'll say this much: the lifetime of the return type of show_init is valid for as long as the owned type passed into the other argument is valid (in other words, for as long as the lifetime of T in other: &mut T is valid).

To fully understand lifetimes in Rust, I recommend reading the lifetime chapter in TRPL Book and lifetime variance in the Rustonomicon.

Testing

With all this in place, let's test our Extend implementation.

#![no_std]
extern crate std;
use arrayvec::ArrayVec;

mod arrayvec { /* ...`ArrayVec` implementation. */ }

const CAP: usize = 5;

fn main() {
    // { /* A: ...earlier code */ }
    // { /* B: ...earlier code */ }
    // { /* C: ...earlier code */ }
    // { /* D: ...earlier code */ }
    {
        // E:
        // Test Extend implementation with iterators on ArrayVec.

        /* Testing for two scenarios;

        1. `arr_vec1` has more CAP (array "capacity" - N) than `arr_vec2`
        has elements to fill it. Meaning, `arr_vec1` will retain spare CAP.

        2. `arr_vec1` has less CAP (array "capacity" - N) than `arr_vec2`
        has elements to fill it. Meaning, `arr_vec1` will max it's CAP
        without extending all of `arr_vec2`s elements.
        */

        // Scenario 1:
        type ArrayVecCap10<T> = ArrayVec<T, 10>;
        type ArrayVecCap5<T> = ArrayVec<T, 5>;

        let mut arr_vec1: ArrayVecCap10<u8> = ArrayVec::new();
        let mut count;
        for i in 0..3 { // Add elements to `arr_vec1`.
            count = 1 + i as u8;
            arr_vec1.try_push(count).unwrap();
        }

        let mut arr_vec2: ArrayVecCap5<u8> = ArrayVec::new();
        for i in 0..2 { // Add elements to `arr_vec2`.
            count = 1 + i as u8;
            arr_vec2.try_push(count).unwrap();
        }

        arr_vec1.extend(arr_vec2); // Extend moves `arr_vec2`.

        let mut empty_arr_vec: ArrayVecCap10<Option<u8>> = ArrayVec::new();
        std::println!("---\n{:?}", arr_vec1.show_init(&mut empty_arr_vec));
        drop(empty_arr_vec); /* Choosing to explicity drop (or free, or
        deallocate) the stack memory consumed by `empty_arr_vec` here
        as it's no longer in use.
        */

        // Scenario 2:
        let mut arr_vec1: ArrayVecCap5<i8> = ArrayVec::new();
        for i in -2..0 { arr_vec1.try_push(i as i8).unwrap(); }

        let mut arr_vec2: ArrayVecCap10<i8> = ArrayVec::new();
        for i in -5..0 { arr_vec2.try_push(i as i8).unwrap(); }

        arr_vec1.extend(arr_vec2); // Extend moves `arr_vec2`.

        let mut empty_arr_vec: ArrayVecCap5<Option<i8>> = ArrayVec::new();
        std::println!("{:?}", arr_vec1.show_init(&mut empty_arr_vec));
        /* Don't need to explicity drop `empty_arr_vec` here as before
        because this is the end of the scope, and the Rust Compiler (rustc)
        will call the drop method in ArrayVec's destructor `Drop`
        to drop `empty_arr_vec` implicity.
        */
    }
}

Figure 17: Testing the implementation of Extend for ArrayVec, and a few other examples.

Returns:

# ...earlier output.
---
[Some(1), Some(2), Some(3), Some(1), Some(2), None, None, None, None, None]
[Some(-2), Some(-1), Some(-5), Some(-4), Some(-3)]

Figure 18: Terminal return from running code in Figure 17.

We introduce type aliasing in Rust using ArrayVecCap10<T> and ArrayVecCap5<T>, reducing repeatability, improving readability.

In Scenario 1, we extend arr_vec1 with arr_vec2 but not fill it up, leaving some slots uninitialized, therefore show_init returns a shared slice displaying Some(u8) for initialized slots and None for uninitialized slots, as planned and implemented. All's good.

In Scenario 2, we do the opposite extending arr_vec1 with arr_vec2 filling it up but not iterating over all the items of arr_vec2 as arr_vec1's capacity buffer had been reached. Showing our implementation of Extend::extend works.

Test successful.

In conclusion

I wasn't planning for this article to be 5,000+ words (as the previous article), well, here we are 😅, but I'm happy I divulged as much useful information as possible, here, to help you improve your understanding of iterators in Rust. If you read till the end give yourself a pat on the back, and thank you for reading my content.

This article ends the experiment of building heapless data structures and learning from them. There is a well known Rust crate that takes the concepts we've implemented here and in the previous article to build and offer battle-tested heapless data structures useful in no_std and embedded environments. The Rust crate is called heapless.

You can find and play around with the full code on Rust Playground via this link: https://play.rust-lang.org/?version=stable&mode=debug&edition=2024&gist=7b80863ed153627d1d86a6ee41a42167
You can also find the whole code on this GitHub Gist: https://gist.github.com/allwelldotdev/39c817ca8d40fe5aeb808eb6301a18ff

👏🏾 Kudos for finishing the article.

Hi there! I'm Allwell, a passionate Rust developer currently working from Lagos, Nigeria. You can connect with me on X (@allwelldotdev) or LinkedIn (Allwell Agwu-Okoro). Let's build and learn Rust together.

How to build a Heapless Vector using `MaybeUninit` for Better Performance.

Allwell — Tue, 04 Nov 2025 12:37:22 +0000

Finally understand MaybeUninit<T> and why it offers better performance over Option<T>, and learn to safeguard unsafe Rust with safe APIs.

TL:DR: Heapless Vector in no_std Rust.

Rust stores data on the stack (fast, fixed-size), heap (growable but needs alloc), or static (program-long); for memory-tight embedded systems, use #![no_std] to ditch heap-alloc like Vec<T> and build a "heapless vector" on stack with a fixed-size array [T; N] tracked by len. Start safe with Option<T> (extra space for None tracking), then optimize to MaybeUninit<T> (exact T size, no overhead) using unsafe methods like write(), as_ptr(), assume_init_read(), and custom Drop—gains 1.5–2x speed and half memory overhead, but requires careful invariants in unsafe Rust to avoid undefined behaviour. (Generated with AI, Grok.)

In this article, I'll teach you how to build a heapless vector data structure with the example of one I already built. I'll share the performance benefits and unsafety to look out for and avoid when using MaybeUninit<T> over Option<T>. Lastly, I'll show you how to build safe APIs on top of unsafe Rust code to ensure "safe unsafe code" in Rust.

A little primer on Rust memory models before we begin. Though to fully comprehend this article you may require practical understanding of Rust memory models—what's stored where, how, and what for—here's a little primer incase you're new to this.

Rust's Memory Model

Rust models memory in three main spaces or regions; the stack, the heap, and static memory.

The stack is a short-lived, fixed-size memory region with LIFO (Last In First Out) movement. The stack stores data of function-local variables, primitive types, function parameters, and fixed-size collections like an array. When a function is called a contiguous chunk of memory is allocated to the top of the stack known as a frame.

The heap is a dynamic, growable region of contiguous memory. Collections and data in the heap are growable and variably-sized. The heap isn't tied to the current call stack (i.e. main function stack frame) of the program, meaning data in the heap can live forever until explicitly deallocated.

Static memory is a catch-all term for several closely related regions located in the file your program is compiled into. These regions are automatically loaded into your program's memory when that program is executed. Values in static memory live for the entire execution of your program (as described by Jon Gjengset in Rust for Rustaceans). Static memory stores source code, 'static lifetime values, and values in static variables. Static memory is read-only by default, therefore immutable. Mutating data in static memory is unsafe (e.g. mutating static variables using static mut).

How does data behave in these different memory regions? We've already seen some examples in the paragraph on the heap, discussing further:

Data in the stack is allocated/deallocated automatically (LIFO order) when entering/exiting scopes (i.e. function stack frames). Access is very fast. Data size must be known at compile time. No manual management of stack data in Rust (this is what we'll be building in this article using Vec<T> as an example).
- Example: let x: i32 = 42; – x lives on the stack during its scope.
Data in the heap is allocated at runtime. Generally slower than the stack due to pointer indirection and potential fragmentation. Is managed using smart pointers (e.g. Box<T>, Rc<T>, Arc<T>, etc.) with Rust's ownership system ensuring safety.
- Example: let v = vec![1, 2, 3]; – the vector's buffer is on the heap.
Data in static memory is allocated at compile time into the program's binary with a fixed memory address. Immutable by default, as we talked about, and mutable with unsafe code. The data's lifetime starts when the program starts and ends when the program ends.
- Example: static HELLO: &str = "Hello"; – HELLO is stored statically and accessible anywhere.

Hope you enjoyed that primer because now we move onto answering the question: why would we need a heapless vector data structure in the first place?

Rust without the Standard Library

There's a practice in Rust known as "Rust without the standard library" communicated in code with the crate attribute #![no_std]. To answer our earlier question, we need to understand this practice.

Usually when you write, build and run Rust code, you most likely do it on a platform with an operating system and a sizeable amount of both RAM memory and disk space (i.e. your laptop or remote server). And sometimes, you write Rust code that is to be executed in environments without an operating system and with limited memory and storage size. This is usually the case when you build for embedded systems, where the code is closer to the bare metal (metaphorically to mean a microcontroller or an SoC). Furthermore, in these "unorthodox" environments, such as those without an operating system, or those without the ability to dynamically allocate memory; how does Rust, as a low level systems programming language, enable us build software that runs in these environments? Through the "Rust without the standard library" (#![no_std]) practice. Let's elaborate further on how it works.

By default, Rust comes packaged with the standard library std and library preludes that bring into scope popularly-used types like Option<T>, Result<T>; traits like Iterator, Debug, Clone, Drop; functions like std::mem::drop, std::mem::size_of; and macros like std::println! and std::dbg!. What you may not know about the standard library is that it is a composite makeup of two of Rust's more fundamental libraries core and alloc. In fact, many types and functions in std are just re-exports from those two libraries.

alloc is Rust's dynamic memory allocation library. It's what makes heap allocation data types like Box<T> and Vec<T> work by either manually implementing a memory allocator with the GlobalAlloc trait or using the system allocator (which is usually the one dictated by the standard C library). Without alloc, collections, smart pointers, and dynamically-allocated strings String in the standard library std won't work.

The core library sits at the bottom of the Rust library pyramid and contains functionality that only depends on the Rust language itself and the hardware the Rust program is running on—meaning core doesn't depend on anything else. alloc sits on top of core in the Rust library hierarchy. So you can begin to see the order of library dependency:
std -[depends on]-> alloc -[depends on]-> core.

When we use the crate attribute #![no_std], we are saying we want to change default action of Rust to instead remove access to std and alloc and only keep core. This ensures std is not compiled with source code and changes the Rust library prelude from std::prelude to core::prelude. This doesn't mean you can't access std in a #![no_std] environment, you still can using extern crate std but accessing std will have to be explicit and dependent on if the target platform (i.e. the environment where your Rust code will run) allows std. The same rule applies for alloc in the sense that Rust allows you the ability to dynamically allocate memory in a #![no_std] environment, that said, this action also has to be explicit and is dependent on two things:

you manually implementing a memory allocator if the target platform does not have one,
if the target platform allows implementation of a system allocator. A couple things might hinder this, one example is if there's too little memory to permit dynamic memory allocation.

Now you see, in embedded environments (i.e. microcontrollers and SoCs) where limitations on compute and memory are prevalent we must make do with data stored on the stack and static memory. We cannot use the heap memory because in such environments we lack memory allocation. That means bye-bye to flexible data structures like Vec<T>. Looking at what we have available by default in Rust core, the closest stack data structure akin to Vec<T> is the core::array (aka. array) primitive type, typed in code as [T; N]. But we know the limitations of array compared to Vec<T>, for example;

array must be fixed-sized to N, Vec<T> is variably-sized,
denoting an array as [T; N] means T must be Copy (shorthand lingo for T must implement the Copy trait),
array creates a fixed-size contiguous space where each space is data stored in the stack memory, while Vec<T> allocates memory in the heap and returns a pointer (off on a tangent here: understanding the difference between a value, variable, and pointer in Rust greatly contributes to improving your understanding of pointers),
plus a couple more differences that are not important to our use case otherwise would mention where applicable.

Despite these differences and limitations between array and Vec<T>, as the more similar data structures, it'd be nice to be able be create a Vec-like data structure that fundamentally functions like an array (therefore, without needing heap allocation) but inherits (not to be confused with OOP Inheritance as Rust doesn't do that) some functionality of Vec<T>—a heapless vector data structure. That's what we'll build next.

Building a Heapless Vector Type

Now you understand the what and the why, let's talk about the how.

To build a heapless vector you must allocate enough memory upfront (in the form of the N size of elements in a [T; N] array)—either in static memory or in a function stack frame—for the largest number of elements you expect the vector to be able to hold, and then augment it with a usize that tracks how many elements it currently holds. To push to the vector, you write to the next element in the (statically sized) array and increment a variable that tracks the number of elements. If the vector's length ever reaches the static size, the next push fails.

First, we'll do this using Option<T> to depict allocating memory upfront using safe Rust with a minimal performance overhead compared to the next option (as time-space complexity is dependent on N elements). Then, using MaybeUninit<T> with uninitialized memory, using unsafe Rust, with better performance. In both cases, we'll work with const generics. Finally, let's dig into some code.

Using `Option<T>`

#[derive(Debug)]
pub struct ArrayVec<T, const N: usize>
where
    T: Copy
{
    values: [Option<T>; N],
    len: usize,
}

impl<T, const N: usize> ArrayVec<T, N>
where
    T: Copy
{
    pub fn new() -> Self {
        ArrayVec {
            values: [None; N],
            len: 0,
        }
    }

    pub fn try_push(&mut self, t: T) -> Result<(), T> {
        if self.len == N {
            return Err(t);
        }
        self.values[self.len] = Some(t);
        self.len += 1;
        Ok(())
    }
}

ArrayVec is generic over both the type of its elements, T, and the maximum number of elements, N. ArrayVec is represented as an array of N optional Ts. With ArrayVec generic over const N: usize, N, must be known at compile time allowing the vector to be stored on the stack while using runtime information to manage how we access the array.

Testing ArrayVec with some code, we can see how it works and how to interact with it.

const SIZE: usize = 5;

fn main() {
    let mut arr_vec1 = ArrayVec::<i32, SIZE>::new();
    println!("{:?}", arr_vec1); // view ArrayVec after init

    let mut count = 0;

    for i in 0..SIZE {
        count = 10 + i as i32;
        arr_vec1.try_push(count).unwrap();
    }
    println!("{:?}", arr_vec1); // view ArrayVec after pushing elements

    // Pushing elements beyond ArrayVec len; should return Err
    let err = arr_vec1.try_push(count + 1);
    println!("{:?}", err);

    // arr_vec does not change
    println!("{:?}", arr_vec1);
}

Running the code above returns:

# Stdout:
ArrayVec { values: [None, None, None, None, None], len: 0 }
ArrayVec { values: [Some(10), Some(11), Some(12), Some(13), Some(14)], len: 5 }
Err(15)
ArrayVec { values: [Some(10), Some(11), Some(12), Some(13), Some(14)], len: 5 }

Notice in our code, we haven't added the #![no_std] crate attribute yet. We will do that in the next section on MaybeUninit<T>.

We can see that Option<T> works as the optional type that holds a valid value when we have successfully pushed a value, T, and None when we haven't. So what is the performance overhead caused by Option<T> here?

Working in a limited environment like that of embedded systems, we really want to be conservative with our use of storage (if any) and memory space. That means storing None in, for example, an array of 1_000_000 N values, where each None is byte-aligned to the size of T if T does not allow niche optimization for Option<T>, is wasteful compared to the alternative and carries performance overhead for the array, and thus our ArrayVec implementation.

For brevity, I'm not going to talk about type alignment and layout in Rust but it goes a long way to help you comprehend, for example, what it means for "None to be byte-aligned to the size of T." Therefore, if you don't know about it I highly recommend you learn of it.

Niche optimization is an optimization technique implemented by the Rust compiler rustc on Option<T> if T cannot be null or zeroed. It's a technique where the wrapper Option type uses the same size as T by assigning it's None with the 0 bit. That way if T is 8 bytes, Option<T> will also be 8 bytes instead of 16 bytes.

If the previous paragraphs were tough to understand, It might help to study type alignment and layout in Rust, as well as niche optimization by the Rust Compiler (rustc) in more detail.

You can experiment with the code of a heapless vector type with Option<T> on the Rust playground via the link: https://play.rust-lang.org/?version=stable&mode=debug&edition=2024&gist=a32ad95d9ad32d06d69bb7a612e57c4b
You can also find the whole code on this GitHub Gist: https://gist.github.com/allwelldotdev/10630be265c9548bfb0c591767afedf2

Let's look at the more performant but unsafe alternative with MaybeUninit<T>.

Using `MaybeUninit<T>`

MaybeUninit<T> is a union type, and union types in Rust are rare and mostly used for interfacing with C code through foreign function interfaces (FFI). Accessing the field of a union in Rust is unsafe, therefore, we'll be introducing the use of unsafe code to implement MaybeUninit<T>.

What is the function of MaybeUninit<T>, how is it useful in the concept of building a heapless vector type?

What does uninitialized mean?

According to stdlib docs, MaybeUninit<T> is a wrapper type to construct uninitialized instances of T. What does "uninitialized" mean? I'll use the example of let value-to-variable assignment to illustrate the meaning of initialized vs. uninitialized instances to help you really understand what MaybeUninit<T> does.

Check out the code below.

let init_var: i32 = 10; /* `init_var` is a variable that holds a 32-bit signed
integer and is immediately initialized to the value of 10. */

let uninit_var; /* In contrast, `uninit_var` is a variable that, at this point,
holds nothing (actually holds what are known as "garbage bytes" - invalid,
overwritable data in memory). Meaning, `uninit_var` points to *uninitialized*
memory.

At this point of the code, in safe code, Rust would *not* allow you use
`uninit_var` in any kind of computation that requires `uninit_var` to
be initialized. The compiler will complain that `uninit_var` is uninitialized
and using it would result in unexpected/undefined behaviour (UB). To use
`uninit_var`, we must initialize it with the appropriate value. */

uninit_var: u8 = 255; /* Finally, we initialize `uninit_var` with an 8-bit
unsigned integer of value 255. Rust's powerful type inference sets `uninit_var`
to be of type `u8`. If you try to assign `uninit_var` to a value of the wrong
type, the compiler will panic. */

/* Below is another example of Rust's type inference enforcing appropriate value
assignment. */
let uninit_var: i8; /* Variable holds no value and points to unitialized memory of
type 8-bit signed integer. */
uninit_var = 255; /* ❌ ERROR: You must initialize `uninit_var` with the
appropriate value. `i8::MAX` is 127. */

Therefore, in a nutshell, uninitialized memory are regions that haven't been filled with valid data yet. Accessing uninitialized memory through normal types like i32 or String leads to UB because the compiler assumes all values are properly initialized (e.g., references are not null, bools are true or false, and padding bytes in structs are not garbage).

Here's another a more elaborate definition: MaybeUninit<T> lets you represent potentially uninitialized data without immediate UB. It's a union type with #[repr(transparent)], meaning it has the exact same size, alignment, and application binary interface (ABI) as T—no overhead. Unlike Option<T>, it doesn't track initialization at runtime (no discriminant), so you must manually ensure safety via invariants (promises you make in unsafe code). Dropping a MaybeUninit<T> never calls T's destructor; that's your job if it's initialized.

According to stdlib docs, "MaybeUninit<T> serves to enable unsafe code to deal with uninitialized data. It is a signal to the compiler indicating that the data here might not be initialized. The compiler then knows to not make any incorrect assumptions or optimizations on this code. You can think of MaybeUninit<T> as being a bit like Option<T> but without any of the run-time tracking and without any of the safety checks."
Learn more about MaybeUninit<T> from the stdlib docs.

Having understood what MaybeUninit<T> is, let's see it's function in building a heapless vector type.

Rewriting the earlier implementation of ArrayVec from Option<T> to MaybeUninit<T>:

#![no_std] // Explicity stating this crate does not use `std`

mod arrayvec {
    use core::mem::MaybeUninit;

    #[derive(Debug)]
    pub struct ArrayVec<T, const N: usize> {
        values: [MaybeUninit<T>; N],
        len: usize,
    }

    impl<T, const N: usize> ArrayVec<T, N> {
        /// Creates a new empty ArrayVec with an array of uninitialized `T`
        /// and `len` = 0.
        pub fn new() -> Self {
            ArrayVec {
                // values: unsafe { MaybeUninit::uninit().assume_init() },
                // Below is same as the commented code above but safer.
                values: [const { MaybeUninit::uninit() }; N],
                len: 0,
            }
        }

        /// Pushes `T` if all `N` elements have not been initialized;
        /// else returns `Err(T)`.
        pub fn try_push(&mut self, value: T) -> Result<(), T> {
            if self.len == N {
                return Err(value);
            }
            self.values[self.len].write(value);
            self.len += 1;
            Ok(())
        }
    }
}

First, notice the newly added crate attribute #![no_std] that signifies the code is built for an environment without support for the Rust standard library. Next, we move ArrayVec and its implementations into a mod to mimic an organized project structure and visibility. values is now an array of N maybe uninitialized values MaybeUninit<T>. len continues to track the number of initialized elements.

Following similar implementations on ArrayVec with Option<T>, now with MaybeUninit<T>:

new introduces allocation to static memory with const and the MaybeUninit::uninit() associated function to return an array of uninitialized instances of T to the values field. In place of the safe variant we could also use the unsafe variant with .assume_init() on MaybeUninit<T> to create and assign an array of N uninitialized instances of T to the values field, as seen in the commented code, because it returns the same value. Let me explain.
- When you declare a field like values: [MaybeUninit<T>; N] in a struct, Rust doesn't require (or perform) any explicit initialization of the array's contents to a "valid" state for T at construction time. Instead the array starts in a raw, uninitialized memory state (i.e., whatever garbage bytes happen to be on the stack at that moment), and the MaybeUninit<T> wrapper semantically interprets those bytes as "uninitialized" without any runtime cost or safety violation. Hence the reason I used the safe variant instead and commented the unsafe variant. Meaning the unsafe variant was safe to use in that context anyway but I chose to go with safe Rust. Other places where I use unsafe, I document (i.e. comment) the safety invariants that make using the unsafe code safe.
try_push acts like .push on Vec<T>, takes in and writes T directly to uninitialized memory in the array (if all N elements have not been initialized, otherwise returns Err(T)) and increments len to track number of initialized elements.

Add `get` and `pop` Methods

In full vector style, let's add more useful methods to ArrayVec like get, pop, and a getter len.

// ...earlier code.

mod arrayvec {
    // ...earlier code.

    impl<T, const N: usize> ArrayVec<T, N> {
        // ...earlier code.

        /// Returns a reference to the element at `index` if within bounds
        /// and initialized; else returns `None`.
        ///
        /// SAFETY: Unsafe internally: Assumes the first `len` slots are
        /// initialized.
        pub fn get(&self, index: usize) -> Option<&T> {
            if index >= self.len {
                return None;
            }
            unsafe { Some(&*self.values[index].as_ptr()) }
        }

        /// Pops the last value, if any, returning owned `T` (or `None`
        /// if empty).
        ///
        /// SAFETY: Uses `.assume_init_read()` to extract (read) and mark
        /// memory as uninitialized (this is also helped by the
        /// decrementing of `self.len` for the next `try_push`).
        pub fn pop(&mut self) -> Option<T> {
            if self.len == 0 {
                return None;
            }
            self.len -= 1;
            Some(unsafe { self.values[self.len].assume_init_read() })
        }

        /// Getter for current length.
        pub fn len(&self) -> usize {
            self.len
        }
    }
}

While implementing get and pop methods on ArrayVec, we use unsafe and document safety invariants (i.e. guarantees) that describe safety rules we upheld to ensure a safe implementation of unsafe code, and we introduced methods like .as_ptr() and .assume_init_read() that allow us to reach into the initialized instances of MaybeUninit<T> and perform computation on them.

In get we take in an index value that points to the array data we want to get. Before we perform the get operation on the values array we ensure we're only getting initialized indexed values by using the if statement to return None otherwise. After returning an initialized indexed value from the values array, we obtain it's immutable raw pointer using .as_ptr(), dereference the raw pointer to access its value using * (this action requires unsafe), then return a shared reference & of the value in the Some variant.

pop takes a mutable reference of self because it mutates self.len, checks before popping if the array is empty (returns None if empty), and decrements self.len to track the un-initialization of formerly initialized memory caused by the .assume_init_read() method call on MaybeUninit<T>. .assume_init_read() is an unsafe function that acts similar to core::ptr::read or std::ptr::read in that it performs a bitwise copy of T whether T is Copy or not. This means if T is not Copy it moves T. Such that if the memory location of T is accessed after .assume_init_read() was called on that same memory location, it will result in UB (similar to a use-after-free error). This is why .assume_init_read() is perfect for an array pop operation on MaybeUninit<T> values and returns owned T in a Some variant. To ensure the use of unsafe code is safe, we first check the array is not empty guaranteeing it contains initialized instances of T that we can call .assume_init_read() on to extract T.

Add Destructor

Lastly, remember what I said earlier in the article when I described MaybeUninit<T>, I said, "dropping a MaybeUninit<T> never calls T's destructor; that's your job if it's initialized." Using this knowledge, next, we implement Drop for ArrayVec to deallocate the N initialized instances of MaybeUninit<T> in the values array.

// ...earlier code.

mod arrayvec {
    // ...earlier code.

    // Implement Drop for ArrayVec to safely deallocate initialized elements.
    impl<T, const N: usize> Drop for ArrayVec<T, N> {
        fn drop(&mut self) {
            /* SAFETY: Explicitly drops the first `len` initialized elements.
            Therefore, no double frees. */
            for i in 0..self.len {
                unsafe {
                    self.values[i].assume_init_drop();
                }
            }
        }
    }
}

We implement a destructor for ArrayVec that the compiler calls to drop (i.e. free or deallocate) ArrayVec when it goes out of scope.

Inside the drop function, we iterate through the self.values array and call .assume_init_drop() on each initialized instance of MaybeUninit<T> which drops the contained value T in place. The safety invariant satisfied here is we explicitly drop only the first self.len initialized elements, we don't touch the uninitialized T. Because calling .assume_init_drop() when T is not yet fully initialized causes UB.

Converting to a `slice`

We've come quite far already but there's just a little more to do to enable us debug the values pushed into ArrayVec. If we try to use ArrayVec as it is in this moment, we'll receive an incoherent output. To help your understanding, here's a code example:

#![no_std]
extern crate std;
use arrayvec::ArrayVec;

mod arrayvec { /* ...`ArrayVec` implementation. */ }

const CAP: usize = 5;

fn main() {
    // Create ArrayVec with 16-bit unsigned integer and array of `CAP` size.
    let mut arr_vec = ArrayVec::<u16, CAP>::new();
    let mut count: u16 = 0;

    // Iterate and push values into ArrayVec.
    for i in 0..(CAP - 2) {
        count = 10 + i as u16;
        arr_vec.try_push(count).unwrap();
    }

    // Print ArrayVec to stdout for debugging.
    std::println!("{:?}", arr_vec);
}

If I ran this code with cargo run I'd get the following output:

# Stdout:
ArrayVec { values: [MaybeUninit<u16>, MaybeUninit<u16>, MaybeUninit<u16>, MaybeUninit<u16>, MaybeUninit<u16>], len: 3 }

Notice how the size of the array is 5 yet the number of initialized elements is 3 (tracked by the len field of ArrayVec), and we cannot see the values pushed into the array instead we see MaybeUninit<u16>. That is precisely the reason why we need to be able to convert ArrayVec to a slice so we can peep into it's initialized values and debug what was inserted or computed in there.

What's a slice? A slice is a primitive type in Rust that is a dynamically-sized view into a contiguous sequence, denoted by [T]. Yes a slice is dynamically-sized though that has nothing to do with heap allocation. A slice is dynamically-sized because a slice is a fat (or wide) pointer that holds information about a location in memory and a length. In other words, a slice is a view into a block of memory represented as a pointer and a length. Learn more about slices in Rust via the stdlib docs.

Using a slice, we can take a view into ArrayVec for its initialized elements. To do that, we implement methods on ArrayVec that allow us convert it into a slice.

// ...earlier code.

mod arrayvec {
    // ...earlier code.

    // Add methods to convert ArrayVec into a slice.
    impl<T, const N: usize> ArrayVec<T, N> {
        // ...earlier code.

        /// Return a slice using `slice::from_raw_parts()`. Returns a slice
        /// over initialized elements (i.e. first `self.len` slots).
        ///
        /// SAFETY: Unsafe internally, but safe API: assumes invariant holds.
        /// Length points to valid length of init elements.
        pub fn as_slice(&self) -> &[T] {
            unsafe {
                core::slice::from_raw_parts(
                    self.values.as_ptr() as *const T, self.len
                )
            }
        }

        /// Returns a mutable slice over initialized elements.
        ///
        /// SAFETY: Length param is valid length of init elements.
        pub fn as_mut_slice(&mut self) -> &mut [T] {
            unsafe {
                core::slice::from_raw_parts_mut(
                    self.values.as_mut_ptr() as *mut T, self.len
                )
            }
        }
    }
}

core::slice::from_raw_parts() and core::slice::from_raw_parts_mut() are unsafe functions therefore you must call them inside unsafe blocks. Both take in a raw pointer (immutable and mutable respectively) and the length of the slice which corresponds, in our case, to the length of initialized elements which we track with self.len.

Modifying the main() function from before slightly (as seen below) we'll be able to debug the values pushed in.

// ...earlier code.

fn main() {
    /* ...earlier code.
    After creating ArrayVec and pushing values into it.
    See similar earlier code for this missing section. */

    // Repeat initial ArrayVec print.
    std::println!("{:?}", arr_vec);

    // Print ArrayVec *now as slice* to stdout for debugging.
    std::println!("---\nInit values: {:?}", arr_vec.as_slice());
}

Returns:

# Stdout:
ArrayVec { values: [MaybeUninit<u16>, MaybeUninit<u16>, MaybeUninit<u16>, MaybeUninit<u16>, MaybeUninit<u16>], len: 3 }
---
Init values: [10, 11, 12]

As you can see, now we can properly debug values pushed or computed in ArrayVec.

Let's conclude with a couple final tests on ArrayVec to showcase its function.

Testing

Let's test our heapless vector type altogether now.

#![no_std]
extern crate std;
use arrayvec::ArrayVec;

mod arrayvec { /* ...`ArrayVec` implementation. */ }

const CAP: usize = 5;

fn main() {
    let mut arr_vec = ArrayVec::<i32, CAP>::new();
    std::println!("{:?}", arr_vec); // View init ArrayVec

    let mut count;

    // Push a few elements
    for i in 0..(CAP - 2) {
        count = 1 + i as i32;
        arr_vec.try_push(count).unwrap()
    }
    std::println!("{:?}", arr_vec); // View pushed elements

    // Return elements in initialized index.
    let arr_els = arr_vec.as_slice();
    std::println!("---\nInit values: {:?}", arr_els);

    // Pop from MaybeUninit ArrayVec; if uninit, return None.
    std::println!("---\nArrayVec `len` before pop: {}", arr_vec.len());
    std::println!("Popped value: {:?}", arr_vec.pop());
    std::println!("ArrayVec `len` after pop: {}", arr_vec.len());

    // TEST: Add more elements beyond `CAP` size for ArrayVec;
    // `try_push` should escape and return with Err.
    let arr_len = arr_vec.len();
    count = *arr_vec.get(arr_len - 1).unwrap(); /* I can deref the pointer
    for the value here without moving the value because I know it's a
    primitive value which enables bitwise copy. */
    let mut arr_err_els: ArrayVec<Result<(), i32>, CAP> =
        ArrayVec::new();

    for _ in arr_len..(CAP * 2) {
        count += 1;
        if let Err(value) = arr_vec.try_push(count) {
            arr_err_els.try_push(Err(value)).unwrap();
        }
    }
    std::println!("---\nFilled ArrayVec: {:?}", arr_vec.as_slice());
    std::println!("Err beyond ArrayVec: {:?}", arr_err_els.as_slice());
}

Returns:

ArrayVec { values: [MaybeUninit<i32>, MaybeUninit<i32>, MaybeUninit<i32>, MaybeUninit<i32>, MaybeUninit<i32>], len: 0 }
ArrayVec { values: [MaybeUninit<i32>, MaybeUninit<i32>, MaybeUninit<i32>, MaybeUninit<i32>, MaybeUninit<i32>], len: 3 }
---
Init values: [1, 2, 3]
---
ArrayVec `len` before pop: 3
Popped value: Some(3)
ArrayVec `len` after pop: 2
---
Filled ArrayVec: [1, 2, 3, 4, 5]
Err beyond ArrayVec: [Err(6), Err(7), Err(8), Err(9), Err(10)]

In conclusion

We've come a long way to learn how to build a heapless vector data structure using uninitialized values. From understanding how Rust models memory regions, to learning about how to configure Rust for unorthodox or constrained environments using the Rust without the Standard Library #![no_std] practice, to building a heapless vector type ArrayVec using Option<T>, and then to optimizing ArrayVec further by replacing Option<T> default values with MaybeUninit<T> uninitialized values in the array.

In optimizing ArrayVec to MaybeUninit<T> from Option<T>, here are some of the advantages and tradeoffs.

Advantages

Performance:
- Reduced memory footprint. Exact size_of::<T>() per element/index in array (no discriminant overhead); halves space for non-niche types like i32 (4 bytes vs. 8 bytes), cutting cache misses in large arrays.
- Faster Access & No Branching. Direct ptr reads/writes via unsafe { Some(&*self.values[index].as_ptr()) }; skips Option's runtime is_some() checks. According to benchmark tests, this yields 1.5–2x speed in loops (e.g., 23ms vs. 62ms for 100M elements in an array).
Ergonomic:
- Simpler hot-path code. Cleaner push/pop without enum wrapping/unwrapping.
Other:
- Heapless/Embedded Fit. Zero-cost abstraction for #![no_std]; enables const init and SIMD-friendly uninit masking, ideal for real-time systems.

Tradeoffs

Safety risk. Introduces unsafe code; UB if invariants violated (e.g., reading uninit slots)—needs Miri testing vs. Option's compile-time guards.
Ergonomic: More boilerplate. Manual drops (with assume_init_drop()) and init tracking (with self.len); less intuitive for beginners than Option's automatic discriminant and destructor (Drop).
Maintenance overhead. Needing explicit lifetime management (with impl<T, const N: usize> Drop for ArrayVec<T, N>).

This effort shows you can build sophisticated data structures using only the stack and static memory, omitting heap allocation. This kind of data structure is useful in embedded systems programming where heap allocation is often unavailable.

You can experiment with the code of a heapless vector type with MaybeUninit<T> on the Rust playground via the link (PS. In the code file, you'll see I've added more features to ArrayVec like the ability for iteration and so on): https://play.rust-lang.org/?version=stable&mode=debug&edition=2024&gist=7b80863ed153627d1d86a6ee41a42167
You can also find the whole code on this GitHub Gist: https://gist.github.com/allwelldotdev/39c817ca8d40fe5aeb808eb6301a18ff

In another article, I'll extend this knowledge by sharing how to make ArrayVec and its fundamental types (&ArrayVec and &mut ArrayVec) iterable (i.e. how to use ArrayVec in a for loop in Rust and more). Stay connected for that!

👏🏾 Kudos for finishing the article.

How to Setup a GitHub SSH connection like a PRO.

Allwell — Tue, 30 Apr 2024 07:59:18 +0000

Discover a more secure and simpler way to push, pull, and clone repositories through GitHub to your local Git repo, or vice versa. The setup is not so simple, which is why many never do it. But once you learn to do it, implement, and use it overtime…you’ll never want to go back to passwords and passphrases.

A better understanding of SSH connections

Hey, like you, for a while, I struggled to wrap my head around what SSH is and how it works. Until several practises, study, and courses; now I finally have a good understanding of the Secure Shell, or SSH for short.

SSH, or Secure Shell, is a way to securely connect and operate a computer over a network, such as the internet. It lets you log in to another computer, execute commands, and transfer files, all while keeping the data safe from outsiders. Think of it as a secure and private conversation between two computers.

It’s a much safer form of secure connection, than passwords. With passwords, hackers have the option of a brute-force hack where they enlist a software that uses probability techniques to guess at your correct password with numerous tries in seconds. With SSH connections, if the hacker doesn’t have access to your private key, there’s no chance or luck of a hack.

How an SSH connection works

You generate an SSH key-pair. Two keys; one is the public key, the other, the private key. These keys are encrypted, meaning they’re not designed to be readable or make much sense, they are hashed. You can also call them hashes or encryption hashes.

The private key stays in your local machine or account while the public key is transferred into the remote machine, server, or account, you want to access.

To authenticate yourself, upon access, the private key is used to decrypt the public key which informs the remote machine, server, or account, that you’re the rightful owner or authorized user.

Okay, enough with the theories, you came here for the how-to guide. Let’s get to it.

Setting up a GitHub SSH connection

GitHub offers multiple forms of secure connection. The default is password-protection. You’re probably using this one, if you’ve not tried to any other means of secure connection.

Today, I’m gonna be sharing how you setup your own SSH connection to GitHub from your local machine. This article may favour Windows users more because I am a Windows user myself, though I’ll endeavour to spot the differences in practise for MacOS users as I spot them.

STEP 1: Check for generated key-pairs in your SSH directory.

Check if you already have keys in your global SSH directory. You may already have keys on your local machine (or PC), check using the command below in your terminal (Git Bash, for Windows PCs).

ls -al ~/.ssh/

STEP 2: Generate an SSH key-pair.

If you find that you do have keys in your SSH directory and you’re certain those keys are for GitHub, then delete them (we’ll create new ones).

If the keys in your SSH directory are not for GitHub, we’ll create new ones for GitHub.

If you do not see any keys at all—FYI, keys look like these id_rsa , id_rsa.pub , id_ed25519 , id_ed25519.pub —not a problem, we’ll create new ones for GitHub.

Before we generate SSH key-pairs, there’re a few things to know and keep in mind.

Public keys are keys that are suffixed with ‘.pub’. Private keys are keys that are not suffixed with anything, including ‘.pub’, in other words, private keys have no suffixes (sometimes this may vary, but if it does it’ll be explicitly specified).
There are four common SSH key types by algorithm: Digital Signature Algorithm (DSA), Rivest-Shamir-Adleman (RSA), Elliptic curve based algorithms, and Ed25519. GitHub currently accepts three of these, namely; RSA, ECDSA and ED25519.
ED25519 is a modern public-key algorithm that offers better security than RSA and is faster in operation. RSA remains the most common and provides the broadest system compatibility.

Having this in mind, we’ll be creating an SSH key-pair using the RSA host key signature algorithm. Let’s begin. Type the command below into your terminal (Git Bash, for Windows PCs).

ssh-keygen -t rsa -b 4096 -C "github your@email_address.com" -N "" -f "/c/Users/YourUsername/.ssh/id_rsa_github"

Let me break it down for you.

ssh-keygen : This command is used to generate, manage, and convert authentication keys for SSH.
-t rsa : Specifies the type of key to create, in this case, RSA.
-b 4096 : Sets the key strength to 4096 bits, which is a good choice for security.
-C "github your@email_address.com" : Adds a comment to the key. It's useful for identifying the key's purpose or owner. Here, change the email to your GitHub email.
-N "" : This specifies an empty passphrase for the key, meaning the key will not require a passphrase to use. This is less secure but more convenient (we’ll come back to why I did this later in the article).
-f "/c/Users/YourUsername/.ssh/id_rsa_github" : Specifies the filename of the key file. This command saves the generated key to a file named id_rsa_github in your .ssh directory. This is useful if you have multiple SSH keys and want to keep them organized. Here, change ‘YourUsername’ to your PC username. We could have used a file path that look like this -f "~/.ssh/id_rsa_github" but may likely throw an error that reads something like "Saving key '~/.ssh/id_rsa_github' failed: No such file or directory”. This is because the Shell does not recognize the file path. This is a common issue when using Git Bash on Windows, due to differences in how Unix-like systems and Windows handle file paths. Therefore you need to use an absolute path, which is the one I recommended in the command.

Running the command above in your terminal will generate two key-pairs and store them in your ‘.ssh’ directory. When you navigate to the ‘.ssh’ directory, you’ll see two keys id_rsa_github.pub (public key), and id_rsa_github (private key).

STEP 3: Transfer your SSH public key to GitHub.

Copy the public key into the clipboard, because we’re about to paste it into our GitHub account to complete the process. Use the command below to do so.

clip < ~/.ssh/id_rsa_github.pub

Now, the public key is in the clipboard, log into your GitHub account, navigate to the Settings page, click the ‘New SSH key’ button, insert/paste the public key into the textarea presented, give it a title, and save by clicking ‘Add SSH key’.

Now, you’ve added your SSH public key into the GitHub servers.

STEP 4: Test your GitHub SSH connection.

Time to test your connection. Run the command below in your terminal.

ssh -i ~/.ssh/id_rsa_github -T git@github.com

This code runs a pseudo-terminal, hence the -T flag, that tests your SSH connection authentication with GitHub servers.

If you followed the steps correctly the command run should return something like this:

Hi (yourGitHubUserName)! You’ve successfully authenticated, but GitHub does not provide shell access.

Hurray! Your GitHub connection is complete, right? Not quite.

Notice that when you run the same SSH connection test without specifying the path—using this flag -i ~/.ssh/id_rsa_github — to your private key, it returns an error that reads like this:

git@github.com: Permission denied (publickey)

This is because the SSH client isn't automatically finding your key because it's not named with one of the default expected filenames (like id_rsa, id_ecdsa, id_ed25519).

To make SSH automatically use your custom-named key—which we named as ‘id_rsa_github’—for GitHub, you have to set up an SSH configuration file to automatically apply specific settings for GitHub.

Doing it like a PRO

So, you’re in the PRO game now. To ensure your SSH connection test works when you simply run the command ssh -T git@github.com , you need to use an SSH config file, as stated in the previous paragraph. Here’s how to do it.

Following from step 4 into…

STEP 5: Setup an SSH Config file.

Create a SSH config file using your favourite text editor (for me, I’ll use vscode). Type the command into the terminal.

code ~/.ssh/config

Add the following configuration to the file:

Host github.com
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_rsa_github
    IdentitiesOnly yes

Replace ~/.ssh/id_rsa_github with the actual path to your SSH key (which may be the same path as the example if you followed through with everything I said to do, and did not make any personal changes to the filename).
IdentitiesOnly yes ensures that only the specified key is used for the connection, which can speed up the connection process by not offering other keys.

Save and exit the file.

Now, if you try to test your SSH connection again without specifying the path to the private key. Like so:

ssh -T git@github.com

This should now work and return:

Hi (yourGitHubUserName)! You’ve successfully authenticated, but GitHub does not provide shell access.

Fantastic!

My work here is done (in the voice of Thanos).

And that’s how you setup a GitHub SSH connection like a PRO.

Alternatives to consider

Notice, I didn’t ask you to set a passphrase when we generated an SSH key-pair? That was on purpose. If you’d added a passphrase to your SSH key-pair generation command—by adding content to the -N flag, the process would be slightly different and more bogus, as you’ll have to work with an ssh-agent command, as well as commands such as eval and ssh-add to make it work. Plus, the incessant prompting to input your passphrase into the terminal to decrypt your private key each time you want to SSH connect to GitHub. It gets tiring after a while and is not convenient.

Soon, you’ll realize there’s little to no difference between a passphrase-enabled SSH connection and a password-protected connection to GitHub. That’s why I purposefully did not set a passphrase for the key-pair we generated. This would ensure that your SSH connections to GitHub are always convenient and noninteractive.

Essentially, this means, whenever you use the PC you setup a GitHub SSH connection on to push repos to, pull, and clone repos from GitHub, you’ll not be prompted to input any password or passphrase; the authentication will happen in the background. Which is how I and many other developers and engineers like it. I hope you’ll like it too.

Enjoy.

Thank you for reading.

Stay curious. Stay healthy.

PS. I’ve published this article on LinkedIn and Medium. I’d like to ask you to, please give it a like and share so others may benefit from it too. Thank you again.

I reduced to just 2 steps the deployment of a LAMP stack + Laravel app using Bash Shell Scripting, Vagrant, and Ansible.

Allwell — Fri, 26 Apr 2024 16:48:26 +0000

Hi there, Cloud and DevOps Enthusiasts, Engineers, and readers, my name is Allwell and I’m currently learning Cloud Computing & Engineering. With this article, I aim to share with you how I automated the deployment of a LAMP stack (Linux, Apache, MySQL, PHP) and Laravel app using bash shell scripting, Vagrant, and Ansible, down to just two simple steps.

Automation can be defined as the simplification and streamlining of a process, where tasks that previously required multiple manual steps are configured to operate with minimal human intervention. This often involves using technology to execute tasks automatically, reducing the need for manual input to just a few or even a single step. The goal of automation is to increase efficiency, reduce errors, and free up human resources for more complex activities.

At a bootcamp I’m attending known as AltSchool Africa (learning Cloud/DevOps Engineering), for second semester exams, I was tasked to do the following:

Project Exam Summary: Automatically provision multiple VMs (Virtual Machines) (2 - master & slave), create bash script to deploy LAMP Stack on master vm/node, use Ansible to execute the bash script on slave vm/node.

Extended Project Exam Question:

Automate the provisioning of two Ubuntu-based servers, named “Master” and “Slave”, using Vagrant.
On the Master node, create a bash script to automate the deployment of a LAMP stack (Linux, Apache, MySQL, PHP).
1. This script should clone a Laravel PHP application from GitHub, install all necessary packages, and configure Apache web server and MySQL.
2. Ensure the bash script is reusable and readable.
Using an Ansible playbook:
1. Execute the bash script on the Slave node and verify that the PHP application is accessible through the VM’s IP address (take a screenshot of this as evidence).
2. Create a cronjob to check the server’s uptime every 12 am.

Firing up my Virtual Machines (VMs)

Solution: I created, or in engineering terms; fired up, two virtual machines (vm) using a vm automation tool known as Vagrant.

Let’s call the host vm, Master, and the server vm, Slave.

After initializing a Vagrant box (a Vagrant term for ‘an OS instance’), I wrote the init file - Vagrantfile, as seen below (my Vagrantfile config):

# -*- mode: ruby -*-
# vi: set ft=ruby :

Vagrant.configure("2") do |config|
  # configure general VM
  config.vm.box = "ubuntu/jammy64"

  # configure master vm
  config.vm.define "master" do |master|
    master.vm.hostname = "master"
    master.vm.network "private_network", ip: "192.168.56.10"
  end

  # configure slave vm
  config.vm.define "slave" do |slave|
    slave.vm.hostname = "slave"
    slave.vm.network "private_network", ip: "192.168.56.11"
  end 

  # provision both vms
  config.vm.provision "shell", inline: <<-SHELL

  # update system
  sudo apt-get update
  SHELL
end

config.vm.box = "ubuntu/jammy64" This line states the operating system of the both vms is Ubuntu 22.04 LTS (Jammy Jellyfish).
config.vm.define "master" do |master| & config.vm.define "slave" do |slave| These lines tell Vagrant to fire up two virtual machines, one called master and the other slave.
master.vm.network "private_network", ip: "192.168.56.10" & slave.vm.network "private_network", ip: "192.168.56.11" These lines tell Vagrant to configure both vms with private static IPs so I can access them via a browser. The master vm is assigned the ip 192.168.56.10, while the slave vm is assigned the ip 192.168.56.11.
There’s a huge part of the Vagrantfile code that is not visible yet, and that’s because the rest of the code is about provisioning for both vms, which I will talk about in detail later in this article. For now, let’s move on to writing the bash script to deploy a LAMP stack.

The Bash Shell Script, or simply Bash Script.

The bash script was the major hurdle in this task because it was the lifeblood that was required for the entire operation to run. The rest of the tasks were mostly automation scripts and software. Below, I break down the bash script into bits (as much I can).

The task: Deploy a LAMP stack, clone the Laravel repo from GitHub, install all necessary packages, and configure the Apache web server, MySQL, and PHP.

#!/bin/bash

# Exit bash script upon any erors
set -e

# Define a function to run when an error occurs
error_handling() {
    echo "The script failed due to a fault"
    echo "Error on line $1 of bash script"
}

# Trap any ERR signal and call error_handling function with the line number
trap 'error_handling $LINENO' ERR

# ----------------------------------------------------------

# Source the 'deploy-LAMP-stack.cfg' configuration file
echo -e "\n###################################################"
echo "Sourcing 'deploy-LAMP-stack.cfg' configuration file..."
sleep 2

# Define path to the configuration file
CONFIG_FILE="$HOME/deploy-LAMP-stack.cfg"

# Check if the file exists, then source config file, or exit script
if [[ -f "$CONFIG_FILE" ]]; then
    # Source configuration file
    source $HOME/deploy-LAMP-stack.cfg
    echo "Configuration file loaded successfully..."
    echo -e "\n###################################################"
else
    echo "Configuration file does not exist in user's home directory"
    echo "Add configuration file 'deploy-LAMP-stack.cfg' to user's home directory - /home/user/"
    echo -e "\n###################################################"
    exit 1 # Exit the script with an exit/return status of 1 indicating an error
fi

# Ensure no interactive prompt during installation or while running script
export DEBIAN_FRONTEND=noninteractive

# Update Linux system package repo
echo -e "\n###################################################"
echo "Updating and upgrading your system..."
echo -e "\n###################################################"
sudo apt update -y

# Apache2 Installation
echo -e "\n###################################################"
echo "Installing Apache2..."
echo -e "\n###################################################"
sudo apt install apache2  -y

# Enable mod_rewrite for Apache2
sudo a2enmod rewrite

# Adjust Firewall to Allow Web Traffic
sudo ufw allow in "Apache Full"

# MySQL Installation
echo -e "\n###################################################"
echo "Installing MySQL..."
echo -e "\n###################################################"
sudo apt install mysql-server -y

# Secure MySQL Installation
echo -e "\n###################################################"
echo "Securing SQL Installation"
echo -e "\n###################################################"
sudo mysql_secure_installation <<EOF

y
n   
y
y
y
y
EOF

# PHP Installation
echo -e "\n###################################################"
echo "Installing PHP 8.2..."
echo -e "\n###################################################"
sudo add-apt-repository -y ppa:ondrej/php
sudo apt update
sudo apt install php8.2 -y

# PHP 8.2 Extensions Installation
echo -e "\n###################################################"
echo "Installing required PHP 8.2 extensions..."
echo -e "\n###################################################"
sudo apt install php8.2-cli php8.2-common php8.2-fpm php8.2-mysql php8.2-zip php8.2-gd php8.2-mbstring php8.2-curl php8.2-xml php8.2-bcmath php8.2-intl php8.2-zip libapache2-mod-php8.2 git unzip -y

# Restart Apache to load new config
sudo systemctl restart apache2

# Composer Installation
echo -e "\n###################################################"
echo "Installing Composer..."
echo -e "\n###################################################"

curl -sS https://getcomposer.org/installer | sudo php -- --install-dir=/usr/local/bin --filename=composer --quiet

# Clone Laravel project from GitHub
echo -e "\n###################################################"
echo "Cloning Laravel from GitHub..."
echo -e "\n###################################################"
cd /var/www/html
sudo git clone https://github.com/laravel/laravel.git
cd laravel

# Composer Dependencies Installation
echo -e "\n###################################################"
echo "Installing Composer dependencies..."
echo -e "\n###################################################"
sudo composer install --no-interaction --prefer-dist --optimize-autoloader --working-dir=/var/www/html/laravel

# Setup MySQL Database
echo -e "\n###################################################"
echo "Setting up MySQL database..."
echo -e "\n###################################################"
sudo mysql -u root -p$DBPASS <<MYSQL_SCRIPT
CREATE DATABASE $DBNAME;
CREATE USER '$DBUSER'@'localhost' IDENTIFIED BY '$DBPASS';
GRANT ALL PRIVILEGES ON $DBNAME.* TO '$DBUSER'@'localhost';
FLUSH PRIVILEGES;
MYSQL_SCRIPT

# Set permissions for Laravel storage and bootstrap cache directories
echo -e "\n###################################################"
echo "Setting permissions for Laravel, storage and bootstrap cache directories..."
echo -e "\n###################################################"
sudo chown -R www-data:www-data /var/www/html/laravel
sudo chmod -R 775 /var/www/html/laravel/storage /var/www/html/laravel/bootstrap/cache

# Setup Laravel environment file
echo -e "\n###################################################"
echo "Configuring Laravel environment..."
echo -e "\n###################################################"
sudo cp .env.example .env
sudo sed -i "s/DB_CONNECTION=sqlite/DB_CONNECTION=mysql/" .env
sudo sed -i 's/^# DB_HOST=127.0.0.1/DB_HOST=127.0.0.1/' .env
sudo sed -i 's/^# DB_PORT=3306/DB_PORT=3306/' .env
sudo sed -i "s/^# DB_DATABASE=laravel/DB_DATABASE=$DBNAME/" .env
sudo sed -i "s/^# DB_USERNAME=root/DB_USERNAME=$DBUSER/" .env
sudo sed -i "s/^# DB_PASSWORD=/DB_PASSWORD=$DBPASS/" .env
php artisan migrate

# Clear and cache Laravel Artisan configurations
echo "Clearing and caching configurations..."
php artisan config:clear
php artisan cache:clear

# Generate Laravel key
echo -e "\n###################################################"
echo "Generating Laravel key..."
echo -e "\n###################################################"
sudo php artisan key:generate

# Configure Apache to serve the Laravel project
echo -e "\n###################################################"
echo "Configuring Apache to serve Laravel..."
echo -e "\n###################################################"
sudo tee /etc/apache2/sites-available/laravel.conf <<EOF
<VirtualHost *:80>
    ServerAdmin webmaster@localhost
    DocumentRoot /var/www/html/laravel/public
    <Directory /var/www/html/laravel/public>
        Options Indexes FollowSymLinks MultiViews
        AllowOverride All
        Require all granted
    </Directory>
    ErrorLog ${APACHE_LOG_DIR}/error.log
    CustomLog ${APACHE_LOG_DIR}/access.log combined
</VirtualHost>
EOF

# Enable the Laravel site
sudo a2ensite laravel.conf
sudo a2dissite 000-default.conf
sudo systemctl restart apache2

# LAMP stack + Laravel deployment: success
echo -e "\n###################################################"
echo "LAMP stack and Laravel are installed."
echo -e "\n###################################################"
echo "Script executed successfully."

Let’s call the bash script “deploy-LAMP-stack.sh”.

My goal for creating this script was to ensure it fully ran automatically, on its own, without any human input, prompt, or type interactions. I was thinking of a situation where I want to configure multiple vms at one go and want to fire them all up just by clicking the play button, and be certain about the safety and accuracy of the operation. This initiative forced me to make this bash script my own and tweak it beyond requirements to match my goal.

Here’s how I achieved that.

To ensure the script is built to be reliable with zero interaction, I set the script to exit upon any errors and inserted an error handler function to catch the error line number, upon runtime, and display it to me so I can fix it in dev mode.

# Exit bash script upon any erors
set -e

# Define a function to run when an error occurs
error_handling() {
    echo "The script failed due to a fault"
    echo "Error on line $1 of bash script"
}

# Trap any ERR signal and call error_handling function with the line number
trap 'error_handling $LINENO' ERR

Though, I didn’t want to, I concluded that I may have to create an external config file that contained the user-input variables required to run the script for things like setting up the MySQL database. Remember, I did this in the bid to ensure no interactivity in runtime but also ensure security of user input. Let’s call the external config file “deploy-LAMP-stack.cfg”.

# Configuration file for 'deploy-LAMP-stack.sh' shell script
DBNAME="laravel_db"
DBUSER="laravel_user"
DBPASS="laravel_pass"

I sourced the variables assigned in the external config file into the script and wrote an ‘if’ statement to check if the file exists then source the variables and run the script, otherwise, if the file does not exist, echo (or post) to runtime that the file does not exit and request it be inserted for script to run.
sleep 2 I added this line to make it seem like the script was taking time (just 2 seconds) to search for the external config file. A touch of user experience there. Haha.

# Source the 'deploy-LAMP-stack.cfg' configuration file
echo -e "\n###################################################"
echo "Sourcing 'deploy-LAMP-stack.cfg' configuration file..."
sleep 2

# Define path to the configuration file
CONFIG_FILE="$HOME/deploy-LAMP-stack.cfg"

# Check if the file exists, then source config file, or exit script
if [[ -f "$CONFIG_FILE" ]]; then
    # Source configuration file
    source $HOME/deploy-LAMP-stack.cfg
    echo "Configuration file loaded successfully..."
    echo -e "\n###################################################"
else
    echo "Configuration file does not exist in user's home directory"
    echo "Add configuration file 'deploy-LAMP-stack.cfg' to user's home directory - /home/user/"
    echo -e "\n###################################################"
    exit 1 # Exit the script with an exit/return status of 1 indicating an error
fi

This line was another attempt to ensure the script runs non-interactively—no user prompts, no type prompts, no popups; just run.

# Ensure no interactive prompt during installation or while running script
export DEBIAN_FRONTEND=noninteractive

Then, the real fun begins. I start by updating my LinuxOS, which, remember, was set to Ubuntu 22.04 (Jammy Jellyfish) in the Vagrantfile. After which, I install and configure Apache2, MySQL, PHP, and PHP extensions. Mostly routine stuff.

# Update Linux system package repo
echo -e "\n###################################################"
echo "Updating and upgrading your system..."
echo -e "\n###################################################"
sudo apt update -y

# Apache2 Installation
echo -e "\n###################################################"
echo "Installing Apache2..."
echo -e "\n###################################################"
sudo apt install apache2  -y

# Enable mod_rewrite for Apache2
sudo a2enmod rewrite

# Adjust Firewall to Allow Web Traffic
sudo ufw allow in "Apache Full"

# MySQL Installation
echo -e "\n###################################################"
echo "Installing MySQL..."
echo -e "\n###################################################"
sudo apt install mysql-server -y

# Secure MySQL Installation
echo -e "\n###################################################"
echo "Securing SQL Installation"
echo -e "\n###################################################"
sudo mysql_secure_installation <<EOF

y
n   
y
y
y
y
EOF

# PHP Installation
echo -e "\n###################################################"
echo "Installing PHP 8.2..."
echo -e "\n###################################################"
sudo add-apt-repository -y ppa:ondrej/php
sudo apt update
sudo apt install php8.2 -y

# PHP 8.2 Extensions Installation
echo -e "\n###################################################"
echo "Installing required PHP 8.2 extensions..."
echo -e "\n###################################################"
sudo apt install php8.2-cli php8.2-common php8.2-fpm php8.2-mysql php8.2-zip php8.2-gd php8.2-mbstring php8.2-curl php8.2-xml php8.2-bcmath php8.2-intl php8.2-zip libapache2-mod-php8.2 git unzip -y

# Restart Apache to load new config
sudo systemctl restart apache2

Then, Composer. It took me almost a whole day to resolve Composer issues. It kept on bugging my script. I eventually figured it out and installed Composer appropriately. This flag --install-dir=/usr/local/bin set the installation directory to an executable path. This ensures that running composer as an executable command is possible. This flag --filename=composer set the filename of the installed executable to ‘composer’. This flag --quiet set the installation to run noninteractively.

# Composer Installation
echo -e "\n###################################################"
echo "Installing Composer..."
echo -e "\n###################################################"

curl -sS https://getcomposer.org/installer | sudo php -- --install-dir=/usr/local/bin --filename=composer --quiet

Cloned the Laravel app from GitHub.

# Clone Laravel project from GitHub
echo -e "\n###################################################"
echo "Cloning Laravel from GitHub..."
echo -e "\n###################################################"
cd /var/www/html
sudo git clone https://github.com/laravel/laravel.git
cd laravel

Installed Composer dependencies for the Laravel app. The Composer installer looks at the directory where the Laravel app is installed and reads the composer.json file to find dependency requirements for the app. Where it doesn’t see a dependency lock file (which locks the app dependencies to specifics for backwards compatibility and future proofing despite future updates to the Laravel app GitHub repo), that’s generally named a composer.lock file, the Composer Installer installs dependency requirements stated in the composer.json file (which are often latest dependency updates, which can in turn be troublesome for app reliability considering the bugs that are often found in latest, bleeding-edge, app updates).

# Composer Dependencies Installation
echo -e "\n###################################################"
echo "Installing Composer dependencies..."
echo -e "\n###################################################"
sudo composer install --no-interaction --prefer-dist --optimize-autoloader --working-dir=/var/www/html/laravel

Setup MySQL Database with user input variables I stored in the external config file (remember). Set file permissions for Laravel storage and bootstrap cache directories. Setup the Laravel environment .env file. Clear and cache Laravel Artisan configurations. Generate a Laravel key to ensure the security of user sessions and other encrypted data.

# Setup MySQL Database
echo -e "\n###################################################"
echo "Setting up MySQL database..."
echo -e "\n###################################################"
sudo mysql -u root -p$DBPASS <<MYSQL_SCRIPT
CREATE DATABASE $DBNAME;
CREATE USER '$DBUSER'@'localhost' IDENTIFIED BY '$DBPASS';
GRANT ALL PRIVILEGES ON $DBNAME.* TO '$DBUSER'@'localhost';
FLUSH PRIVILEGES;
MYSQL_SCRIPT

# Set permissions for Laravel storage and bootstrap cache directories
echo -e "\n###################################################"
echo "Setting permissions for Laravel, storage and bootstrap cache directories..."
echo -e "\n###################################################"
sudo chown -R www-data:www-data /var/www/html/laravel
sudo chmod -R 775 /var/www/html/laravel/storage /var/www/html/laravel/bootstrap/cache

# Setup Laravel environment file
echo -e "\n###################################################"
echo "Configuring Laravel environment..."
echo -e "\n###################################################"
sudo cp .env.example .env
sudo sed -i "s/DB_CONNECTION=sqlite/DB_CONNECTION=mysql/" .env
sudo sed -i 's/^# DB_HOST=127.0.0.1/DB_HOST=127.0.0.1/' .env
sudo sed -i 's/^# DB_PORT=3306/DB_PORT=3306/' .env
sudo sed -i "s/^# DB_DATABASE=laravel/DB_DATABASE=$DBNAME/" .env
sudo sed -i "s/^# DB_USERNAME=root/DB_USERNAME=$DBUSER/" .env
sudo sed -i "s/^# DB_PASSWORD=/DB_PASSWORD=$DBPASS/" .env
php artisan migrate

# Clear and cache Laravel Artisan configurations
echo "Clearing and caching configurations..."
php artisan config:clear
php artisan cache:clear

# Generate Laravel key
echo -e "\n###################################################"
echo "Generating Laravel key..."
echo -e "\n###################################################"
sudo php artisan key:generate

Now, the final piece is where I configure the Apache2 web server to serve the Laravel project through the web port 80. This means, when you input the IP address of the vm—which we set in the Vagrantfile (remember)—you’ll be able to see the display homepage of the Laravel app. Let’s take note of the display homepage of the Laravel app being the test to certify if our entire script ran correctly, because every other step taken in this script was made to arrive at this point.

# Configure Apache to serve the Laravel project
echo -e "\n###################################################"
echo "Configuring Apache to serve Laravel..."
echo -e "\n###################################################"
sudo tee /etc/apache2/sites-available/laravel.conf <<EOF
<VirtualHost *:80>
    ServerAdmin webmaster@localhost
    DocumentRoot /var/www/html/laravel/public
    <Directory /var/www/html/laravel/public>
        Options Indexes FollowSymLinks MultiViews
        AllowOverride All
        Require all granted
    </Directory>
    ErrorLog ${APACHE_LOG_DIR}/error.log
    CustomLog ${APACHE_LOG_DIR}/access.log combined
</VirtualHost>
EOF

# Enable the Laravel site
sudo a2ensite laravel.conf
sudo a2dissite 000-default.conf
sudo systemctl restart apache2

# LAMP stack + Laravel deployment: success
echo -e "\n###################################################"
echo "LAMP stack and Laravel are installed."
echo -e "\n###################################################"
echo "Script executed successfully."

After the script runs completely (on the master vm), if you input the IP address of the master vm (192.168.56.10) into a browser and hit enter, the browser will display the homepage of the Laravel app that was cloned from GitHub. This confirms that the script ran successfully and the Laravel app is accessible via the master vm.

Ansible, and running the script in the Slave VM.

Once the bash script runs successfully on the master vm the next step is to run the script in the slave vm, using Ansible.

What is Ansible?

Ansible is a tool used to manage and set up different computers and servers automatically, without needing to manually type commands or install software on each one individually. It works by letting you write simple instructions that tell your computers what software to install, what settings to use, and how to communicate with each other. This is especially helpful for people who need to handle many computers at once, as it makes the process much faster and reduces the chance of making mistakes.

The simple instructions you write through Ansible to communicate with computers and servers are called Playbooks, also known as Ansible Playbooks. These Ansible Playbooks are data files written in YAML format.

To run the bash script from the master vm on the slave vm, using Ansible, we need to write an Ansible Playbook.

Here’s how I did that:

First, I created an Ansible Inventory file. Ansible reads this file to know and set the connection mechanism between the master vm and the slave vm. Ansible connects to servers through an SSH connection. For the SSH connection to work, Ansible needs to know the whereabouts (or directory) of the private key with which to connect to the slave vm, that’s what the line below does. ansible_ssh_private_key_file: /home/vagrant/.ssh/id_rsa_slavevm Note: Ansible Inventory files similar to Ansible Playbooks are written YAML format.

all:
  hosts:
    slave:
      ansible_host: 192.168.56.11
      ansible_user: vagrant
      ansible_ssh_private_key_file: /home/vagrant/.ssh/id_rsa_slavevm

The Ansible Playbook, as seen in the code below, which is set to “Deploy LAMP stack/Laravel application and set cron job on Slave node” on the slave vm, runs 6 tasks which are ultimately supposed to facilitate 3 things: transfer the bash script from the master vm to the slave vm, execute the bash script on the slave vm, and set a cronjob to check and log server uptime on the slave vm every 12 am.

---
- name: Deploy LAMP stack/Laravel application and set cron job on Slave node
  hosts: slave

  tasks:
    - name: Transfer Master VM bash script to Slave node
      copy:
        src: /home/vagrant/deploy-LAMP-stack.sh
        dest: /home/vagrant/deploy-LAMP-stack.sh
        mode: "0755"

    - name: Transfer Master VM config file to Slave node
      copy:
        src: /home/vagrant/deploy-LAMP-stack.cfg
        dest: /home/vagrant/deploy-LAMP-stack.cfg
        mode: "0755"

    - name: Remove Windows line endings from bash script
      command: sed -i 's/\r$//' deploy-LAMP-stack.sh
      args:
        chdir: /home/vagrant

    - name: Execute Master VM bash script on Slave node
      command: ./deploy-LAMP-stack.sh
      args:
        chdir: /home/vagrant

    - name: Check if the Laravel application is up and running
      uri:
        url: http://192.168.56.11
        return_content: yes
      register: webpage
      until: webpage.status == 200
      retries: 5
      delay: 10

    - name: Set cron job to check server uptime
      cron:
        name: "Check uptime"
        minute: "0"
        hour: "0"
        job: "uptime >> /var/log/uptime.log"

Transfer Bash Script from Master VM to Slave VM

Even though Vagrant VM provisioning offers a ‘shared folder’ feature which should allow access to the bash script on the slave vm via this path /vagrant/scripts/deploy-LAMP-stack.sh , because the assignment instructed me to execute the bash script created in the master vm in the slave vm, my first task in the Ansible Playbook was to transfer the bash script from the master vm to the slave vm.

- name: Transfer Master VM bash script to Slave node
      copy:
        src: /home/vagrant/deploy-LAMP-stack.sh
        dest: /home/vagrant/deploy-LAMP-stack.sh
        mode: "0755"

Transferring the bash script also meant transferring the config file which is needed to run the bash script.

- name: Transfer Master VM config file to Slave node
      copy:
        src: /home/vagrant/deploy-LAMP-stack.cfg
        dest: /home/vagrant/deploy-LAMP-stack.cfg
        mode: "0755"

The bash script file was created and edited on my WindowsOS PC, therefore, when the file was copied into a LinuxOS machine it had a problem with ‘line endings’ which is a common Windows-Linux problem. To resolve that, I created another task to remove Windows line endings from the bash script file—essentially, changing the file line endings from CRLF to LF [which is suitable for the Linux File System (LFS)].

- name: Remove Windows line endings from bash script
      command: sed -i 's/\r$//' deploy-LAMP-stack.sh
      args:
        chdir: /home/vagrant

Execute Bash Script on Slave VM

Now, the bash script is transferred and configured in the home directory of the vagrant user on slave vm. I wrote a task using the Ansible ‘command’ module to run the bash script file on the slave vm.

- name: Execute Master VM bash script on Slave node
      command: ./deploy-LAMP-stack.sh
      args:
        chdir: /home/vagrant

To check if the bash script ran successfully, and the Laravel application is up and running on the slave vm, I wrote a task using the Ansible ‘uri’ module to check the web status of the slave vm’s IP address 192.168.56.11 .

- name: Check if the Laravel application is up and running
      uri:
        url: http://192.168.56.11
        return_content: yes
      register: webpage
      until: webpage.status == 200
      retries: 5
      delay: 10

Set a Cronjob to Check and Log Server Uptime on the Slave VM Every 12 AM

I wrote a task using the Ansible ‘cron’ module to set a cronjob to check and log server uptime to the path /var/log/uptime.log on the slave vm every 12am.

- name: Set cron job to check server uptime
      cron:
        name: "Check uptime"
        minute: "0"
        hour: "0"
        job: "uptime >> /var/log/uptime.log"

If I’d decided to stop here I’d have already completed the tasks required by my bootcamp and finished my assignment, but I took it a step forward to automate every manual process and fine-tune my work.

Provisioning for both VMs (Master and Slave)

After creating the bash script, confirming it works, writing Ansible Playbook, executing the bash script and setting a cronjob on slave vm, I provisioned the master and slave vm to automate manual steps and things I did within each of the vms during the entire process of my work. I did this to ensure I reduced the number of manual steps it took to perform the entire process again.

This is what my Vagrantfile finally looked like.

# -*- mode: ruby -*-
# vi: set ft=ruby :

Vagrant.configure("2") do |config|
  # configure general VM
  config.vm.box = "ubuntu/jammy64"

  # configure master vm
  config.vm.define "master" do |master|
    master.vm.hostname = "master"
    master.vm.network "private_network", ip: "192.168.56.10"

    # provision master vm
    master.vm.provision "shell", inline: <<-SHELL

    # Provision LAMP stack bash script into user directory
    sudo -u vagrant cp /vagrant/assets/config/deploy-LAMP-stack.cfg /home/vagrant
    sudo -u vagrant cp /vagrant/scripts/deploy-LAMP-stack.sh /home/vagrant
    sudo -u vagrant chmod +x /home/vagrant/deploy-LAMP-stack.sh
    sudo -u vagrant sed -i 's/\r$//' /home/vagrant/deploy-LAMP-stack.sh # remove Windows carriage returns (CR) - Ensure script runs on Linux VM

    # Install and configure Ansible
    sudo add-apt-repository --yes --update ppa:ansible/ansible
    sudo apt install ansible -y
    cd /etc/ansible/
    sudo mv ansible.cfg ansible.cfg_backup
    sudo ansible-config init --disabled -t all > ansible.cfg
    sudo sed -i "s/^;host_key_checking=True/host_key_checking=False/" /etc/ansible/ansible.cfg # Stop Ansible from interaction during ssh login - improve automation process

    # Provision Ansible files into user directory
    sudo -u vagrant cp -r /vagrant/scripts/ansible /home/vagrant
    SHELL

    # provision master vm: Generate SSH key-pair
    master.vm.provision "shell", path: "scripts/ssh_keygen.sh"
  end

  # configure slave vm
  config.vm.define "slave" do |slave|
    slave.vm.hostname = "slave"
    slave.vm.network "private_network", ip: "192.168.56.11"

    # provision slave vm
    slave.vm.provision "shell", inline: <<-SHELL

    # Secure SSH connection
    sudo sed -i "s/^#PermitRootLogin prohibit-password/PermitRootLogin prohibit-password/" /etc/ssh/sshd_config # Turn off password-enabled root ssh login
    sudo sed -i "s/^#PasswordAuthentication yes/PasswordAuthentication no/" /etc/ssh/sshd_config # Turn off password-enabled ssh login
    sudo systemctl restart ssh # Restart ssh service to enable config
    SHELL
  end 

  # provision both vms
  config.vm.provision "shell", inline: <<-SHELL

  # update system
  sudo apt-get update

  # Turn off restart of services - Change line 38 from "#$nrconf{restart} = 'i';" to "#$nrconf{restart} = 'a';"
  sudo apt-get install -y needrestart
  sudo sed -i "38s/#\\$nrconf{restart} = 'i';/#\\$nrconf{restart} = 'a';/" /etc/needrestart/needrestart.conf

  # Ensure SSH is installed & enabled
  sudo apt install openssh-server openssh-client -y
  SHELL
end

This Vagrantfile can be segmented into three parts. One, the config & provisioning of both vms. Two, the config and provisioning of the master vm. Three, the config & provisioning of the slave vm.

Config & Provisioning of both VMS (Master & Slave)

# provision both vms
  config.vm.provision "shell", inline: <<-SHELL

  # update system
  sudo apt-get update

  # Turn off restart of services - Change line 38 from "#$nrconf{restart} = 'i';" to "#$nrconf{restart} = 'a';"
  sudo apt-get install -y needrestart
  sudo sed -i "38s/#\\$nrconf{restart} = 'i';/#\\$nrconf{restart} = 'a';/" /etc/needrestart/needrestart.conf

  # Ensure SSH is installed & enabled
  sudo apt install openssh-server openssh-client -y
  SHELL

Updated both vm app package repositories using this command sudo apt-get update
Set ‘needrestart’ feature for scripts when they installed to ‘a’ which means automatically, instead of ‘i’ which means interactive.
Installed SSH software package on both VMs.

Config & Provisioning of Master VM

# provision master vm
    master.vm.provision "shell", inline: <<-SHELL

    # Provision LAMP stack bash script into user directory
    sudo -u vagrant cp /vagrant/assets/config/deploy-LAMP-stack.cfg /home/vagrant
    sudo -u vagrant cp /vagrant/scripts/deploy-LAMP-stack.sh /home/vagrant
    sudo -u vagrant chmod +x /home/vagrant/deploy-LAMP-stack.sh
    sudo -u vagrant sed -i 's/\r$//' /home/vagrant/deploy-LAMP-stack.sh # remove Windows carriage returns (CR) - Ensure script runs on Linux VM

    # Install and configure Ansible
    sudo add-apt-repository --yes --update ppa:ansible/ansible
    sudo apt install ansible -y
    cd /etc/ansible/
    sudo mv ansible.cfg ansible.cfg_backup
    sudo ansible-config init --disabled -t all > ansible.cfg
    sudo sed -i "s/^;host_key_checking=True/host_key_checking=False/" /etc/ansible/ansible.cfg # Stop Ansible from interaction during ssh login - improve automation process

    # Provision Ansible files into user directory
    sudo -u vagrant cp -r /vagrant/scripts/ansible /home/vagrant
    SHELL

    # provision master vm: Generate SSH key-pair
    master.vm.provision "shell", path: "scripts/ssh_keygen.sh"

Copied the bash script and external config file from the Vagrant shared folder to the Vagrant user home directory, set file permissions, and changed the file line endings from CRLF to LF [which is suitable for the Linux File System (LFS)] using the sed command.
Installed and configured Ansible:
- sudo mv ansible.cfg ansible.cfg_backup backed up the initial Ansible config file.
- sudo ansible-config init --disabled -t all > ansible.cfg created a new Ansible config file.
- sudo sed -i "s/^;host_key_checking=True/host_key_checking=False/" /etc/ansible/ansible.cfg accessed Ansible config file and changed ‘host_key_checking’ variable from True to False. I did this so that Ansible doesn’t ask/prompt an interactive question when the Ansible Playbook is run. Because as a general rule of thumb, you do not want an automated script to prompt an interactive question, ensuring it runs noninteractively is the best way to certify that the script will run uninterrupted once set in motion.
Copied Ansible files (the inventory and playbook file) from the Vagrant shared folder to the Vagrant user home directory.

master.vm.provision "shell", path: "scripts/ssh_keygen.sh" generated ssh key-pair for the master vm through a script called ‘ssh_keygen.sh’. We’ll need this ssh key-pair later to access the slave vm through the master vm.

My provisioning code earlier instructed Vagrant to run script ‘ssh_keygen.sh’ on the master vm. This is what the script ‘ssh_keygen.sh’ looks like. Again, this script runs in such a way that is not interactive.

#!/bin/bash

# Check for existing SSH keys and generate a new one if none exists
if [ ! -f "/home/vagrant/.ssh/id_rsa_slavevm" ]; then
  echo "Generating SSH key..."
  sudo -u vagrant ssh-keygen -t rsa -b 4096 -C "slave vm pka created by Allwell 220424" -N "" -f "/home/vagrant/.ssh/id_rsa_slavevm"
  echo "SSH key generated."
  sudo -u vagrant chmod 400 /home/vagrant/.ssh/id_rsa_slavevm
else
  echo "SSH key already exists."
fi

Config & Provisioning of Slave VM

# provision slave vm
    slave.vm.provision "shell", inline: <<-SHELL

    # Secure SSH connection
    sudo sed -i "s/^#PermitRootLogin prohibit-password/PermitRootLogin prohibit-password/" /etc/ssh/sshd_config # Turn off password-enabled root ssh login
    sudo sed -i "s/^#PasswordAuthentication yes/PasswordAuthentication no/" /etc/ssh/sshd_config # Turn off password-enabled ssh login
    sudo systemctl restart ssh # Restart ssh service to enable config
    SHELL

Secured the SSH server connection on the slave vm in anticipation of a connection from the master vm.
- sudo sed -i "s/^#PermitRootLogin prohibit-password/PermitRootLogin prohibit-password/" /etc/ssh/sshd_config turned off password-enabled root ssh login into the slave vm.
- sudo sed -i "s/^#PasswordAuthentication yes/PasswordAuthentication no/" /etc/ssh/sshd_config turned off password-enabled ssh login.
Restarted the SSH service or daemon to enable the new SSH configurations.

End of Setup

Congratulations on getting to this point of my how-to guide. Finally, my code, provisioning, scripting, and automation is done. Everything works. I’m in awe. I’m elated. I just created something beautiful that runs.

But don’t take my word that it runs, try it for yourself using the links and techniques I’ll share next: how to test that this entire setup works on your own PC.

HOW TO TEST: Deploy LAMP stack through bash script built on Master VM on Slave VM using Ansible.

I’ve published all my code to GitHub (https://github.com/allwelldotdev/altschool-cloud-sem2-project_exam).

Clone my repo and try this.

Prerequisites & Dependencies: You’ll need to have the following software installed on your pc for these tests to work.

Vagrant
Oracle VM Virtualbox Manager
Git Bash (for Windows users).
Web browser.

Things To Do:

Open your Git Bash terminal (for Windows users) or Terminal (for MacOS users).
Clone my GitHub repo, and change directory into my GitHub project.
Apply the command vagrant up && vagrant ssh master to fire up both vms (master & slave) taking configurations and provisions instructions from my Vagrantfile.

At this point, let’s recall, in the title, I stated that I reduced to just 2 steps the deployment of a LAMP stack + Laravel app using Bash Shell Scripting, Vagrant, and Ansible.

Here are the two steps:

Step 1: Copy the Master VM SSH Public Key into the Slave VM ‘authorized_keys’ file.

After firing up both vms using the vagrant up command, and logging into the master vm using vagrant ssh master , next, we’ll copy the master vm ssh public key into the slave vm ‘authorized_keys’ file.

Type in the following command into your terminal and hit enter.
cat ~/.ssh/id_rsa_slavevm.pub
Select and copy the ssh public key ‘id_rsa_slavevm.pub’.
Open another terminal window/process, type the command
vagrant ssh slave to bring up the slave vm, then type the following command into your terminal and hit enter.
vim ~/.ssh/authorized_keys
This will open a vim editor on your terminal. Type ‘o’ then paste the public key into the file by pressing ‘Shift + Ins’.
Close the vim editor by pressing, in this order, ‘Esc’, then ‘:wq’, hit enter. This should save your entry in the file and close the vim editor.

Step 2: Run the Ansible Playbook.

Once you’ve completed Step 1, the next thing to do is run the Ansible Playbook. Remember, because of our master vm provisioning techniques we have already copied our Ansible Playbook and Inventory file from the Vagrant Shared Folder to our Vagrant user home directory on the master vm.

Go back to the other terminal where you’d earlier logged into the master vm. Make sure your working directory is the home directory of the Vagrant user. You can confirm by using the command pwd . It should return /home/vagrant . If it doesn’t, use the command cd /home/vagrant and follow on with the next bullet point.
List the home directory, using the ls command, and you should see the ‘ansible’ directory which was provisioned into the vm. Change directory into the ‘ansible’ directory. In the ‘ansible’ directory are two files: inv.yaml (Ansible Inventory file) and plyabook.yaml (Ansible Playbook file). We would use these files to run the Ansible Playbook.
Run the Ansible Playbook using this command:
ansible-playbook -i inv.yaml playbook.yaml

In Conclusion

Once you run the Ansible Playbook, Ansible, through Python scripts, will execute all the tasks sets in the playbook on the slave vm.

This will complete the assignment, and when you open the slave vm IP address (192.168.56.11) in a browser, you’ll access the landing page of the Laravel App served through the web server (Apache) on the slave vm.

That’s how you deploy a LAMP stack + Laravel App using Bash Shell Scripting, Vagrant, and Ansible with just 2 steps.

Thank you for reading.

Stay healthy. Stay curious.

PS. I’ve published this article on LinkedIn, Medium, and my GitHub. I’d like to ask you to, please give it a like and share so others may benefit from it too. Thank you.

DEV Community: Allwell

How To Make A Custom Type Iterable In Rust.

Iterator Traits

IntoIterator

Implementing IntoIterator for ArrayVec

Implementing IntoIterator for &ArrayVec and &mut ArrayVec

Testing

FromIterator

Testing

Extend

Testing

In conclusion

How to build a Heapless Vector using `MaybeUninit` for Better Performance.

Rust's Memory Model

Rust without the Standard Library

Building a Heapless Vector Type

Using Option<T>

Using MaybeUninit<T>

What does uninitialized mean?

Add get and pop Methods

Add Destructor

Converting to a slice

Testing

In conclusion

How to Setup a GitHub SSH connection like a PRO.

A better understanding of SSH connections

How an SSH connection works

Setting up a GitHub SSH connection

Doing it like a PRO

Alternatives to consider

I reduced to just 2 steps the deployment of a LAMP stack + Laravel app using Bash Shell Scripting, Vagrant, and Ansible.

Firing up my Virtual Machines (VMs)

The Bash Shell Script, or simply Bash Script.

Ansible, and running the script in the Slave VM.

Transfer Bash Script from Master VM to Slave VM

Execute Bash Script on Slave VM

Set a Cronjob to Check and Log Server Uptime on the Slave VM Every 12 AM

Provisioning for both VMs (Master and Slave)

Config & Provisioning of both VMS (Master & Slave)

Config & Provisioning of Master VM

Config & Provisioning of Slave VM

End of Setup

HOW TO TEST: Deploy LAMP stack through bash script built on Master VM on Slave VM using Ansible.

Step 1: Copy the Master VM SSH Public Key into the Slave VM ‘authorized_keys’ file.

Step 2: Run the Ansible Playbook.

In Conclusion

`IntoIterator`

Implementing `IntoIterator` for `ArrayVec`

Implementing `IntoIterator` for `&ArrayVec` and `&mut ArrayVec`

`FromIterator`

`Extend`

Using `Option<T>`

Using `MaybeUninit<T>`

Add `get` and `pop` Methods

Converting to a `slice`